@skewedaspect/sleekspace-ui 0.2.0-beta.1

package/src/composables/useCustomColors.ts

@@ -0,0 +1,124 @@
+//----------------------------------------------------------------------------------------------------------------------
+// Custom Colors Composable
+//----------------------------------------------------------------------------------------------------------------------
+
+import { type Ref, computed } from 'vue';
+
+//----------------------------------------------------------------------------------------------------------------------
+
+/**
+ * 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.
+ *
+ * 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
+ *
+ * @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`
+ *
+ * @returns Computed style object with CSS variables ready to bind to a component's style attribute
+ *
+ * @example Basic usage with base color only
+ * ```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>
+ * ```
+ *
+ * @example With both base and text colors
+ * ```vue
+ * <SkButton base-color="oklch(0.7 0.25 300)" text-color="white">
+ *   Custom Purple Button
+ * </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
+) : 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;
+
+        // Only apply custom colors if baseColor is provided
+        if(!baseColorValue)
+        {
+            return styles;
+        }
+
+        // Set the base color CSS variable
+        const baseVarName = `--sk-${ componentName }-color-base`;
+        styles[baseVarName] = baseColorValue;
+
+        // Set or calculate text color
+        const fgVarName = `--sk-${ componentName }-fg`;
+
+        if(textColorValue)
+        {
+            // Use provided text color
+            styles[fgVarName] = textColorValue;
+        }
+        else
+        {
+            // Fallback to the theme's default text color
+            // Users should provide textColor for optimal contrast
+            styles[fgVarName] = 'var(--sk-neutral-text)';
+        }
+
+        return styles;
+    });
+}
+
+//----------------------------------------------------------------------------------------------------------------------

package/src/composables/usePortalContext.test.ts

@@ -0,0 +1,402 @@
+//----------------------------------------------------------------------------------------------------------------------
+// Portal Context Composable Tests
+//----------------------------------------------------------------------------------------------------------------------
+
+import { describe, expect, it } from 'vitest';
+import { defineComponent, h, inject, provide, ref } from 'vue';
+import { mount } from '@vue/test-utils';
+import { usePortalContext } from './usePortalContext';
+
+//----------------------------------------------------------------------------------------------------------------------
+
+describe('usePortalContext', () =>
+{
+    describe('theme injection', () =>
+    {
+        it('should return default greyscale theme when no provider exists', () =>
+        {
+            const TestComponent = defineComponent({
+                setup()
+                {
+                    const { theme } = usePortalContext();
+                    return { theme };
+                },
+                render()
+                {
+                    return h('div', { 'data-scheme': this.theme });
+                },
+            });
+
+            const wrapper = mount(TestComponent);
+            expect(wrapper.attributes('data-scheme')).toBe('greyscale');
+        });
+
+        it('should inject theme from parent provider', () =>
+        {
+            const TestComponent = defineComponent({
+                setup()
+                {
+                    const { theme } = usePortalContext();
+                    return { theme };
+                },
+                render()
+                {
+                    return h('div', { 'data-scheme': this.theme });
+                },
+            });
+
+            const ParentComponent = defineComponent({
+                setup()
+                {
+                    provide('sk-theme', ref('colorful'));
+                },
+                render()
+                {
+                    return h(TestComponent);
+                },
+            });
+
+            const wrapper = mount(ParentComponent);
+            expect(wrapper.find('div').attributes('data-scheme')).toBe('colorful');
+        });
+
+        it('should be reactive to theme changes', async () =>
+        {
+            const themeRef = ref('greyscale');
+
+            const TestComponent = defineComponent({
+                setup()
+                {
+                    const { theme } = usePortalContext();
+                    return { theme };
+                },
+                render()
+                {
+                    return h('div', { 'data-scheme': this.theme });
+                },
+            });
+
+            const ParentComponent = defineComponent({
+                setup()
+                {
+                    provide('sk-theme', themeRef);
+                },
+                render()
+                {
+                    return h(TestComponent);
+                },
+            });
+
+            const wrapper = mount(ParentComponent);
+            expect(wrapper.find('div').attributes('data-scheme')).toBe('greyscale');
+
+            themeRef.value = 'colorful';
+            await wrapper.vm.$nextTick();
+
+            expect(wrapper.find('div').attributes('data-scheme')).toBe('colorful');
+        });
+    });
+
+    describe('theme re-provision for nested portals', () =>
+    {
+        it('should re-provide theme for child components', () =>
+        {
+            // This child component injects from the re-provided context
+            const ChildComponent = defineComponent({
+                setup()
+                {
+                    const theme = inject('sk-theme', ref('default'));
+                    return { theme };
+                },
+                render()
+                {
+                    return h('span', { 'class': 'child', 'data-theme': this.theme });
+                },
+            });
+
+            // This component uses usePortalContext which re-provides
+            const PortalComponent = defineComponent({
+                setup()
+                {
+                    const { theme } = usePortalContext();
+                    return { theme };
+                },
+                render()
+                {
+                    return h('div', { 'data-scheme': this.theme }, [
+                        h(ChildComponent),
+                    ]);
+                },
+            });
+
+            // Root provides the theme
+            const RootComponent = defineComponent({
+                setup()
+                {
+                    provide('sk-theme', ref('colorful'));
+                },
+                render()
+                {
+                    return h(PortalComponent);
+                },
+            });
+
+            const wrapper = mount(RootComponent);
+            expect(wrapper.find('.child').attributes('data-theme')).toBe('colorful');
+        });
+
+        it('should support nested portal components', () =>
+        {
+            // Inner portal component (like Listbox inside Modal)
+            const InnerPortalComponent = defineComponent({
+                setup()
+                {
+                    const { theme } = usePortalContext();
+                    return { theme };
+                },
+                render()
+                {
+                    return h('div', { 'class': 'inner', 'data-scheme': this.theme });
+                },
+            });
+
+            // Outer portal component (like Modal)
+            const OuterPortalComponent = defineComponent({
+                setup()
+                {
+                    const { theme } = usePortalContext();
+                    return { theme };
+                },
+                render()
+                {
+                    return h('div', { 'class': 'outer', 'data-scheme': this.theme }, [
+                        h(InnerPortalComponent),
+                    ]);
+                },
+            });
+
+            // Root provides the theme
+            const RootComponent = defineComponent({
+                setup()
+                {
+                    provide('sk-theme', ref('colorful'));
+                },
+                render()
+                {
+                    return h(OuterPortalComponent);
+                },
+            });
+
+            const wrapper = mount(RootComponent);
+            expect(wrapper.find('.outer').attributes('data-scheme')).toBe('colorful');
+            expect(wrapper.find('.inner').attributes('data-scheme')).toBe('colorful');
+        });
+
+        it('should handle deeply nested portal components', () =>
+        {
+            const createPortalComponent = (name : string, children : any[] = []) : ReturnType<typeof defineComponent> =>
+            {
+                return defineComponent({
+                    name,
+                    setup()
+                    {
+                        const { theme } = usePortalContext();
+                        return { theme };
+                    },
+                    render()
+                    {
+                        return h('div', { 'class': name, 'data-scheme': this.theme }, children);
+                    },
+                });
+            };
+
+            // Create 5 levels of nested portal components
+            const Level5 = createPortalComponent('level-5');
+            const Level4 = createPortalComponent('level-4', [ h(Level5) ]);
+            const Level3 = createPortalComponent('level-3', [ h(Level4) ]);
+            const Level2 = createPortalComponent('level-2', [ h(Level3) ]);
+            const Level1 = createPortalComponent('level-1', [ h(Level2) ]);
+
+            const RootComponent = defineComponent({
+                setup()
+                {
+                    provide('sk-theme', ref('colorful'));
+                },
+                render()
+                {
+                    return h(Level1);
+                },
+            });
+
+            const wrapper = mount(RootComponent);
+
+            // All levels should receive the theme
+            expect(wrapper.find('.level-1').attributes('data-scheme')).toBe('colorful');
+            expect(wrapper.find('.level-2').attributes('data-scheme')).toBe('colorful');
+            expect(wrapper.find('.level-3').attributes('data-scheme')).toBe('colorful');
+            expect(wrapper.find('.level-4').attributes('data-scheme')).toBe('colorful');
+            expect(wrapper.find('.level-5').attributes('data-scheme')).toBe('colorful');
+        });
+
+        it('should propagate theme changes through all nested levels', async () =>
+        {
+            const themeRef = ref('greyscale');
+
+            const InnerComponent = defineComponent({
+                setup()
+                {
+                    const { theme } = usePortalContext();
+                    return { theme };
+                },
+                render()
+                {
+                    return h('span', { 'class': 'inner', 'data-scheme': this.theme });
+                },
+            });
+
+            const OuterComponent = defineComponent({
+                setup()
+                {
+                    const { theme } = usePortalContext();
+                    return { theme };
+                },
+                render()
+                {
+                    return h('div', { 'class': 'outer', 'data-scheme': this.theme }, [
+                        h(InnerComponent),
+                    ]);
+                },
+            });
+
+            const RootComponent = defineComponent({
+                setup()
+                {
+                    provide('sk-theme', themeRef);
+                },
+                render()
+                {
+                    return h(OuterComponent);
+                },
+            });
+
+            const wrapper = mount(RootComponent);
+
+            expect(wrapper.find('.outer').attributes('data-scheme')).toBe('greyscale');
+            expect(wrapper.find('.inner').attributes('data-scheme')).toBe('greyscale');
+
+            themeRef.value = 'colorful';
+            await wrapper.vm.$nextTick();
+
+            expect(wrapper.find('.outer').attributes('data-scheme')).toBe('colorful');
+            expect(wrapper.find('.inner').attributes('data-scheme')).toBe('colorful');
+        });
+    });
+
+    describe('default behavior without SkTheme', () =>
+    {
+        it('should work without any parent theme provider', () =>
+        {
+            const TestComponent = defineComponent({
+                setup()
+                {
+                    const { theme } = usePortalContext();
+                    return { theme };
+                },
+                render()
+                {
+                    return h('div', { 'data-scheme': this.theme });
+                },
+            });
+
+            const wrapper = mount(TestComponent);
+            // Should default to greyscale
+            expect(wrapper.attributes('data-scheme')).toBe('greyscale');
+        });
+
+        it('should still re-provide default theme for nested components', () =>
+        {
+            const ChildComponent = defineComponent({
+                setup()
+                {
+                    const theme = inject('sk-theme', ref('fallback'));
+                    return { theme };
+                },
+                render()
+                {
+                    return h('span', { 'class': 'child', 'data-theme': this.theme });
+                },
+            });
+
+            const ParentComponent = defineComponent({
+                setup()
+                {
+                    const { theme } = usePortalContext();
+                    return { theme };
+                },
+                render()
+                {
+                    return h('div', [
+                        h(ChildComponent),
+                    ]);
+                },
+            });
+
+            // Mount without any theme provider
+            const wrapper = mount(ParentComponent);
+
+            // Child should receive the default greyscale theme
+            expect(wrapper.find('.child').attributes('data-theme')).toBe('greyscale');
+        });
+    });
+
+    describe('multiple instances', () =>
+    {
+        it('should handle multiple portal components at the same level', () =>
+        {
+            const PortalA = defineComponent({
+                setup()
+                {
+                    const { theme } = usePortalContext();
+                    return { theme };
+                },
+                render()
+                {
+                    return h('div', { 'class': 'portal-a', 'data-scheme': this.theme });
+                },
+            });
+
+            const PortalB = defineComponent({
+                setup()
+                {
+                    const { theme } = usePortalContext();
+                    return { theme };
+                },
+                render()
+                {
+                    return h('div', { 'class': 'portal-b', 'data-scheme': this.theme });
+                },
+            });
+
+            const RootComponent = defineComponent({
+                setup()
+                {
+                    provide('sk-theme', ref('colorful'));
+                },
+                render()
+                {
+                    return h('div', [
+                        h(PortalA),
+                        h(PortalB),
+                    ]);
+                },
+            });
+
+            const wrapper = mount(RootComponent);
+
+            expect(wrapper.find('.portal-a').attributes('data-scheme')).toBe('colorful');
+            expect(wrapper.find('.portal-b').attributes('data-scheme')).toBe('colorful');
+        });
+    });
+});
+
+//----------------------------------------------------------------------------------------------------------------------

package/src/composables/usePortalContext.ts

@@ -0,0 +1,95 @@
+//----------------------------------------------------------------------------------------------------------------------
+// Portal Context Composable
+//----------------------------------------------------------------------------------------------------------------------
+
+import { type Ref, inject, provide, readonly, ref } from 'vue';
+
+//----------------------------------------------------------------------------------------------------------------------
+
+/**
+ * Composable for handling context propagation through portals.
+ *
+ * **The Portal Problem:**
+ * When components use portals (Modal, Dropdown, Tooltip, Listbox, Popover), the portaled content
+ * is teleported to `<body>`, breaking two critical things:
+ *
+ * 1. **CSS Cascade** - CSS custom properties defined on parent elements don't inherit to portaled
+ *    content because it's no longer a DOM descendant.
+ *
+ * 2. **Vue's provide/inject** - The Vue component tree is preserved, but nested portal components
+ *    (e.g., Listbox inside Modal) need the theme re-provided to reach their own portaled content.
+ *
+ * **This composable solves both problems by:**
+ * - Injecting the current theme (with a safe default)
+ * - Re-providing it for any nested portal components
+ * - Returning the theme ref for binding to `data-scheme` on portaled elements
+ *
+ * **IMPORTANT:** All portal components MUST:
+ * 1. Use this composable
+ * 2. Apply `:data-scheme="theme"` to their portaled content root element(s)
+ * 3. Apply kind classes directly on portaled content (CSS can't cascade from parent)
+ *
+ * @returns Object containing:
+ *   - `theme`: Readonly ref of current theme name for `:data-scheme` binding
+ *
+ * @example Basic usage in a portal component
+ * ```vue
+ * <script setup lang="ts">
+ * import { usePortalContext } from '@/composables/usePortalContext';
+ *
+ * const { theme } = usePortalContext();
+ * </script>
+ *
+ * <template>
+ *   <SomePortal>
+ *     <SomeContent :data-scheme="theme" :class="contentClasses">
+ *       <slot />
+ *     </SomeContent>
+ *   </SomePortal>
+ * </template>
+ * ```
+ *
+ * @example With multiple portaled elements (Modal with overlay)
+ * ```vue
+ * <template>
+ *   <DialogPortal>
+ *     <DialogOverlay :data-scheme="theme" />
+ *     <DialogContent :data-scheme="theme" :class="contentClasses">
+ *       <slot />
+ *     </DialogContent>
+ *   </DialogPortal>
+ * </template>
+ * ```
+ *
+ * @remarks
+ * - The default theme is 'greyscale' if no SkTheme wrapper is present
+ * - This composable automatically handles provide/inject - you don't need to do it manually
+ * - The returned `theme` ref is readonly to prevent accidental mutation
+ * - Nested portals (e.g., Dropdown inside Modal) work automatically because each portal
+ *   component re-provides the theme
+ *
+ * **Portal components in this library:**
+ * - SkModal (DialogPortal)
+ * - SkDropdown (DropdownMenuPortal)
+ * - SkDropdownSubmenu (DropdownMenuPortal)
+ * - SkListbox (ComboboxPortal)
+ * - SkTooltip (TooltipPortal)
+ * - SkPopover (PopoverPortal) - future
+ * - SkToast (ToastPortal) - future
+ */
+export function usePortalContext() : { theme : Ref<string> }
+{
+    // Inject the current theme from SkTheme or use default
+    // Always use a ref to ensure reactivity through portals
+    const currentTheme = inject('sk-theme', readonly(ref('greyscale')));
+
+    // Re-provide for nested portal components
+    // This is critical for components like Listbox inside Modal
+    provide('sk-theme', currentTheme);
+
+    return {
+        theme: currentTheme as Ref<string>,
+    };
+}
+
+//----------------------------------------------------------------------------------------------------------------------