@skewedaspect/sleekspace-ui 0.7.0 → 0.8.0

package/src/components/Page/SkPageSidebarToggle.vue

@@ -0,0 +1,148 @@
+<!----------------------------------------------------------------------------------------------------------------------
+  - Page Sidebar Toggle Component
+  --------------------------------------------------------------------------------------------------------------------->
+
+<template>
+    <SkButton
+        v-if="drawer.isAvailable.value"
+        variant="ghost"
+        dense
+        :kind="effectiveKind"
+        :pressed="drawer.isOpen.value"
+        :aria-expanded="drawer.isOpen.value"
+        :aria-label="ariaLabel"
+        :class="classes"
+        @click="drawer.toggle"
+    >
+        <template #icon>
+            <slot>
+                <!-- Default glyphs: hamburger for the sidebar, vertical kebab for the aside. Override
+                     via the default slot with any inline-sized element that inherits currentColor. -->
+                <svg
+                    v-if="side === 'sidebar'"
+                    viewBox="0 0 20 20"
+                    width="20"
+                    height="20"
+                    aria-hidden="true"
+                    focusable="false"
+                >
+                    <path
+                        d="M3 5h14M3 10h14M3 15h14"
+                        stroke="currentColor"
+                        stroke-width="2"
+                        stroke-linecap="round"
+                        fill="none"
+                    />
+                </svg>
+                <svg
+                    v-else
+                    viewBox="0 0 20 20"
+                    width="20"
+                    height="20"
+                    aria-hidden="true"
+                    focusable="false"
+                >
+                    <circle cx="10" cy="4" r="1.6" fill="currentColor" />
+                    <circle cx="10" cy="10" r="1.6" fill="currentColor" />
+                    <circle cx="10" cy="16" r="1.6" fill="currentColor" />
+                </svg>
+            </slot>
+        </template>
+    </SkButton>
+</template>
+
+<!--------------------------------------------------------------------------------------------------------------------->
+
+<script setup lang="ts">
+    /**
+     * @component SkPageSidebarToggle
+     * @description Button that toggles one of SkPage's drawers. Thin wrapper around SkButton -- inherits the
+     * design system's chrome and ghost-variant hover/pressed behavior. Auto-connects to the nearest SkPage
+     * via provide/inject, so no wiring is required; hides itself when the targeted panel is persistent.
+     * Use `side="sidebar"` (default) for the left drawer and `side="aside"` for the right. Default glyph is
+     * a hamburger for the sidebar and a vertical kebab for the aside so both toggles can live in the same
+     * navbar without visual collision; override via the default slot if you want something else.
+     *
+     * @example Twin toggles in a navbar
+     * ```vue
+     * <SkNavBar>
+     *     <template #leading><SkPageSidebarToggle /></template>
+     *     <template #brand>MyApp</template>
+     *     <template #actions><SkPageSidebarToggle side="aside" /></template>
+     * </SkNavBar>
+     * ```
+     *
+     * @slot default - Custom glyph. Replaces the built-in SVG. Should be inline-sized and inherit
+     *                 `currentColor`.
+     */
+
+    import { computed, inject } from 'vue';
+
+    // Types
+    import type { SkButtonKind } from '../Button/types';
+    import type { SkPageDrawerSide } from './types';
+
+    // Components
+    import SkButton from '../Button/SkButton.vue';
+
+    // Composables
+    import { usePageDrawer } from '@/composables/usePageDrawer';
+    import { NAVBAR_KIND_KEY } from '../NavBar/context';
+
+    //------------------------------------------------------------------------------------------------------------------
+
+    export interface SkPageSidebarToggleComponentProps
+    {
+        /**
+         * Which drawer this toggle controls. `sidebar` binds to the left drawer; `aside` binds to the right.
+         * @default 'sidebar'
+         */
+        side ?: SkPageDrawerSide;
+
+        /**
+         * Override the toggle's color kind. By default the toggle inherits the enclosing SkNavBar's
+         * kind (when placed inside one) and falls back to `neutral` otherwise. Pass a kind explicitly
+         * to force a specific color scheme.
+         */
+        kind ?: SkButtonKind;
+
+        /**
+         * Accessible label for the toggle. Screen readers announce this; sighted users see only the glyph.
+         * Defaults to a label matching `side`.
+         */
+        ariaLabel ?: string;
+    }
+
+    //------------------------------------------------------------------------------------------------------------------
+
+    const props = withDefaults(defineProps<SkPageSidebarToggleComponentProps>(), {
+        side: 'sidebar',
+        kind: undefined,
+        ariaLabel: undefined,
+    });
+
+    //------------------------------------------------------------------------------------------------------------------
+
+    const drawer = usePageDrawer(props.side);
+    const navbarKind = inject(NAVBAR_KIND_KEY, null);
+
+    const effectiveKind = computed<SkButtonKind>(() =>
+    {
+        if(props.kind) { return props.kind; }
+        if(navbarKind) { return navbarKind.value as SkButtonKind; }
+        return 'neutral';
+    });
+
+    const ariaLabel = computed<string>(() =>
+    {
+        if(props.ariaLabel) { return props.ariaLabel; }
+        return props.side === 'aside' ? 'Toggle aside' : 'Toggle sidebar';
+    });
+
+    const classes = computed(() => ({
+        'sk-page-sidebar-toggle': true,
+        [`sk-page-sidebar-toggle-${ props.side }`]: true,
+    }));
+</script>
+
+<!--------------------------------------------------------------------------------------------------------------------->

package/src/components/Page/index.ts

@@ -3,6 +3,7 @@
 //----------------------------------------------------------------------------------------------------------------------
 
 export { default as SkPage } from './SkPage.vue';
+export { default as SkPageSidebarToggle } from './SkPageSidebarToggle.vue';
 export * from './types';
 
 //----------------------------------------------------------------------------------------------------------------------

package/src/components/Page/types.ts

@@ -6,22 +6,47 @@ import type { SkThemeName } from '../Theme/types';
 
 //----------------------------------------------------------------------------------------------------------------------
 
-/** Sidebar position */
-export type SkPageSidebarPosition = 'left' | 'right';
+/**
+ * Sidebar / aside rendering mode.
+ * - `auto`: persistent above the matching breakpoint, drawer below. Default.
+ * - `persistent`: always inline, regardless of viewport size.
+ * - `drawer`: always off-canvas, opens over content.
+ */
+export type SkPagePanelMode = 'auto' | 'persistent' | 'drawer';
+
+/** @deprecated Use `SkPagePanelMode`. Retained as an alias. */
+export type SkPageSidebarMode = SkPagePanelMode;
+
+/** Which drawer a toggle button controls. */
+export type SkPageDrawerSide = 'sidebar' | 'aside';
 
 /** Page props interface */
 export interface SkPageProps
 {
-    /** Sidebar position */
-    sidebarPosition ?: SkPageSidebarPosition;
     /** Fixed header (stays at top when scrolling) */
     fixedHeader ?: boolean;
     /** Fixed footer (stays at bottom when scrolling) */
     fixedFooter ?: boolean;
-    /** Custom sidebar width */
+    /** Custom sidebar width. CSS length. */
     sidebarWidth ?: string;
+    /** Custom aside width. CSS length. */
+    asideWidth ?: string;
+    /** Sidebar rendering mode. Defaults to 'auto' (persistent above breakpoint, drawer below) */
+    sidebarMode ?: SkPagePanelMode;
+    /** Aside rendering mode. Defaults to 'auto'. */
+    asideMode ?: SkPagePanelMode;
+    /** Breakpoint below which sidebar `auto` mode switches to drawer. CSS length. Default: 1024px */
+    sidebarBreakpoint ?: string;
+    /** Breakpoint below which aside `auto` mode switches to drawer. CSS length. Default: 1024px */
+    asideBreakpoint ?: string;
+    /** Controlled sidebar drawer open state. When omitted, SkPage manages state internally */
+    sidebarOpen ?: boolean;
+    /** Controlled aside drawer open state. When omitted, SkPage manages state internally */
+    asideOpen ?: boolean;
     /** Optional theme name — when provided, SkPage acts as a theme provider */
     theme ?: SkThemeName;
+    /** Flush layout (no default gap/padding around main area or inside content) */
+    flush ?: boolean;
 }
 
 //----------------------------------------------------------------------------------------------------------------------

package/src/components/ScrollArea/SkScrollArea.vue

@@ -58,6 +58,15 @@
         kind ?: SkScrollAreaKind;
         baseColor ?: string;
         textColor ?: string;
+
+        /**
+         * When true, fade the scrollable edges with a CSS mask so content visibly tapers
+         * into/out of the viewport. Applies to whichever axis (or both) is scrollable.
+         * Override the fade distance via the `--sk-scroll-area-fade` custom property
+         * (default 1.5rem).
+         * @default false
+         */
+        fade ?: boolean;
     }
 
     //------------------------------------------------------------------------------------------------------------------
@@ -68,6 +77,7 @@
         kind: 'neutral',
         baseColor: undefined,
         textColor: undefined,
+        fade: false,
     });
 
     //------------------------------------------------------------------------------------------------------------------
@@ -81,6 +91,8 @@
     const classes = computed(() => ({
         'sk-scroll-area': true,
         [`sk-${ props.kind }`]: true,
+        [`sk-${ props.orientation }`]: true,
+        'sk-fade': props.fade,
     }));
 </script>
 

package/src/components/Select/SkSelectItem.vue

@@ -82,8 +82,8 @@
     //------------------------------------------------------------------------------------------------------------------
 
     const textEl = useTemplateRef<InstanceType<typeof SelectItemText>>('textEl');
-    const register = inject<(value : string, label : string) => void>('sk-select-register', undefined);
-    const unregister = inject<(value : string) => void>('sk-select-unregister', undefined);
+    const register = inject<((value : string, label : string) => void) | undefined>('sk-select-register', undefined);
+    const unregister = inject<((value : string) => void) | undefined>('sk-select-unregister', undefined);
 
     onMounted(() =>
     {

package/src/components/Sidebar/SkSidebar.vue

@@ -86,6 +86,14 @@
          * @default 'left'
          */
         side ?: SkSidebarSide;
+
+        /**
+         * Opts out of the coarse-pointer touch-target floor on sidebar items (44px minimum on
+         * touch devices). Use in compact navigation contexts where density matters more than
+         * tap comfort. No effect on fine-pointer (mouse) devices.
+         * @default false
+         */
+        dense ?: boolean;
     }
 
     //------------------------------------------------------------------------------------------------------------------
@@ -94,6 +102,7 @@
         kind: 'neutral',
         width: '180px',
         side: 'left',
+        dense: false,
     });
 
     //------------------------------------------------------------------------------------------------------------------
@@ -114,6 +123,7 @@
             'sk-sidebar': true,
             [`sk-${ props.kind }`]: true,
             'sk-sidebar-right': props.side === 'right',
+            'sk-dense': props.dense,
         };
     });
 

package/src/components/TreeView/SkTreeView.vue

@@ -12,7 +12,7 @@
         :default-expanded="expandedKeys"
         :class="classes"
         :style="customColorStyles"
-        @update:model-value="$emit('update:modelValue', $event)"
+        @update:model-value="$emit('update:modelValue', $event as T | T[])"
     >
         <template #default="{ flattenItems }">
             <slot :flatten-items="flattenItems" />
@@ -40,11 +40,11 @@
 
     //------------------------------------------------------------------------------------------------------------------
 
-    export interface SkTreeViewComponentProps
+    export interface SkTreeViewComponentProps<TItem extends Record<string, unknown> = Record<string, unknown>>
     {
-        items : T[];
-        getKey : (item : T) => string;
-        modelValue ?: T | T[];
+        items : TItem[];
+        getKey : (item : TItem) => string;
+        modelValue ?: TItem | TItem[];
         multiple ?: boolean;
         propagateSelect ?: boolean;
         kind ?: SkTreeViewKind;
@@ -55,7 +55,7 @@
 
     //------------------------------------------------------------------------------------------------------------------
 
-    const props = withDefaults(defineProps<SkTreeViewComponentProps>(), {
+    const props = withDefaults(defineProps<SkTreeViewComponentProps<T>>(), {
         modelValue: undefined,
         multiple: false,
         propagateSelect: false,

package/src/composables/useFocusTrap.test.ts

@@ -0,0 +1,184 @@
+//----------------------------------------------------------------------------------------------------------------------
+// Focus Trap Composable Tests
+//----------------------------------------------------------------------------------------------------------------------
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { defineComponent, h, nextTick, ref } from 'vue';
+import { mount } from '@vue/test-utils';
+import { useFocusTrap } from './useFocusTrap';
+
+//----------------------------------------------------------------------------------------------------------------------
+// Harness
+//
+// Renders a container with a few focusable elements plus an outside button. The active/container
+// refs are exposed on the component instance so tests can flip the trap on and off.
+//----------------------------------------------------------------------------------------------------------------------
+
+function makeHarness(onEscape ?: () => void) : ReturnType<typeof defineComponent>
+{
+    return defineComponent({
+        setup()
+        {
+            const active = ref<boolean>(false);
+            const container = ref<HTMLElement | null>(null);
+            useFocusTrap({ active, container, onEscape });
+            return { active, container };
+        },
+        render()
+        {
+            return h('div', [
+                h('button', { id: 'outside', type: 'button' }, 'outside'),
+                h(
+                    'div',
+                    {
+                        ref: 'container',
+                        tabindex: '-1',
+                    },
+                    [
+                        h('button', { id: 'first', type: 'button' }, 'first'),
+                        h('input', { id: 'middle', type: 'text' }),
+                        h('button', { id: 'last', type: 'button' }, 'last'),
+                    ]
+                ),
+            ]);
+        },
+    });
+}
+
+//----------------------------------------------------------------------------------------------------------------------
+
+describe('useFocusTrap', () =>
+{
+    let root : HTMLDivElement;
+
+    beforeEach(() =>
+    {
+        // happy-dom's elementFromPoint + layout are limited, so stub getClientRects to return
+        // a non-empty list on all our fixture elements (getFocusable filters on rects.length).
+        Element.prototype.getClientRects = vi.fn(() => ({
+            length: 1,
+            item: () => null,
+            *[Symbol.iterator]() { yield { width: 1, height: 1 } as DOMRect; },
+        } as unknown as DOMRectList));
+
+        root = document.createElement('div');
+        document.body.appendChild(root);
+    });
+
+    afterEach(() =>
+    {
+        document.body.removeChild(root);
+        vi.restoreAllMocks();
+    });
+
+    //------------------------------------------------------------------------------------------------------------------
+
+    it('focuses the first focusable descendant when activated', async () =>
+    {
+        const wrapper = mount(makeHarness(), { attachTo: root });
+        wrapper.vm.active = true;
+        await nextTick();
+        // nextTick inside the watcher also runs an async nextTick before focusing; wait one more.
+        await nextTick();
+
+        const first = wrapper.find('#first').element as HTMLButtonElement;
+        expect(document.activeElement).toBe(first);
+        wrapper.unmount();
+    });
+
+    it('restores focus to the previously focused element on deactivate', async () =>
+    {
+        const wrapper = mount(makeHarness(), { attachTo: root });
+        const outside = wrapper.find('#outside').element as HTMLButtonElement;
+        outside.focus();
+
+        wrapper.vm.active = true;
+        await nextTick();
+        await nextTick();
+
+        wrapper.vm.active = false;
+        await nextTick();
+
+        expect(document.activeElement).toBe(outside);
+        wrapper.unmount();
+    });
+
+    it('tab from the last focusable cycles back to the first', async () =>
+    {
+        const wrapper = mount(makeHarness(), { attachTo: root });
+        wrapper.vm.active = true;
+        await nextTick();
+        await nextTick();
+
+        const last = wrapper.find('#last').element as HTMLButtonElement;
+        const first = wrapper.find('#first').element as HTMLButtonElement;
+        last.focus();
+
+        const event = new KeyboardEvent('keydown', { key: 'Tab', bubbles: true });
+        document.dispatchEvent(event);
+        expect(document.activeElement).toBe(first);
+        wrapper.unmount();
+    });
+
+    it('shift-tab from the first focusable cycles to the last', async () =>
+    {
+        const wrapper = mount(makeHarness(), { attachTo: root });
+        wrapper.vm.active = true;
+        await nextTick();
+        await nextTick();
+
+        const first = wrapper.find('#first').element as HTMLButtonElement;
+        const last = wrapper.find('#last').element as HTMLButtonElement;
+        first.focus();
+
+        const event = new KeyboardEvent('keydown', { key: 'Tab', shiftKey: true, bubbles: true });
+        document.dispatchEvent(event);
+        expect(document.activeElement).toBe(last);
+        wrapper.unmount();
+    });
+
+    it('if focus escapes to an element outside the container, tab pulls it back to first', async () =>
+    {
+        const wrapper = mount(makeHarness(), { attachTo: root });
+        wrapper.vm.active = true;
+        await nextTick();
+        await nextTick();
+
+        const outside = wrapper.find('#outside').element as HTMLButtonElement;
+        const first = wrapper.find('#first').element as HTMLButtonElement;
+        // Simulate something stealing focus outside the trap (e.g. a scripted focus call).
+        outside.focus();
+
+        const event = new KeyboardEvent('keydown', { key: 'Tab', bubbles: true });
+        document.dispatchEvent(event);
+        expect(document.activeElement).toBe(first);
+        wrapper.unmount();
+    });
+
+    it('calls onEscape when Escape is pressed while active', async () =>
+    {
+        const onEscape = vi.fn();
+        const wrapper = mount(makeHarness(onEscape), { attachTo: root });
+        wrapper.vm.active = true;
+        await nextTick();
+        await nextTick();
+
+        document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }));
+        expect(onEscape).toHaveBeenCalledTimes(1);
+        wrapper.unmount();
+    });
+
+    it('does not react to keypresses when inactive', async () =>
+    {
+        const onEscape = vi.fn();
+        const wrapper = mount(makeHarness(onEscape), { attachTo: root });
+        // Never activate.
+
+        document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }));
+        document.dispatchEvent(new KeyboardEvent('keydown', { key: 'Tab', bubbles: true }));
+        expect(onEscape).not.toHaveBeenCalled();
+        wrapper.unmount();
+    });
+});
+
+//----------------------------------------------------------------------------------------------------------------------

package/src/composables/useFocusTrap.ts

@@ -0,0 +1,141 @@
+//----------------------------------------------------------------------------------------------------------------------
+// Focus Trap Composable
+//
+// Minimal, dependency-free focus trap for modal/drawer patterns. Traps tab cycling inside a
+// container while active, saves the previously-focused element on activation, and restores it
+// on deactivation. Pair with your own ESC handler and overlay click-to-close as needed.
+//----------------------------------------------------------------------------------------------------------------------
+
+import { type Ref, nextTick, watch } from 'vue';
+
+//----------------------------------------------------------------------------------------------------------------------
+
+const FOCUSABLE_SELECTOR = [
+    'a[href]',
+    'button:not([disabled])',
+    'input:not([disabled]):not([type="hidden"])',
+    'select:not([disabled])',
+    'textarea:not([disabled])',
+    '[tabindex]:not([tabindex="-1"])',
+    'audio[controls]',
+    'video[controls]',
+    'details > summary:first-of-type',
+].join(',');
+
+function getFocusable(container : HTMLElement) : HTMLElement[]
+{
+    const nodes = container.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR);
+    return Array.from(nodes).filter((el) =>
+    {
+        // Reject visually hidden or inert elements.
+        if(el.hasAttribute('inert')) { return false; }
+        if(el.getAttribute('aria-hidden') === 'true') { return false; }
+        const rects = el.getClientRects();
+        return rects.length > 0;
+    });
+}
+
+//----------------------------------------------------------------------------------------------------------------------
+
+export interface UseFocusTrapOptions
+{
+    /** When true, the trap is active: focus moves inside and tab cycling is constrained. */
+    active : Ref<boolean>;
+
+    /** Element whose descendants form the trap region. */
+    container : Ref<HTMLElement | null>;
+
+    /**
+     * Optional callback fired when the user presses Escape. Most consumers will use this to
+     * close the modal/drawer.
+     */
+    onEscape ?: () => void;
+}
+
+/**
+ * Trap focus inside a container while `active` is true. Restores focus to the previously
+ * active element when deactivated.
+ */
+export function useFocusTrap(options : UseFocusTrapOptions) : void
+{
+    const { active, container, onEscape } = options;
+
+    let previouslyFocused : HTMLElement | null = null;
+
+    function handleKeydown(event : KeyboardEvent) : void
+    {
+        if(!active.value || !container.value) { return; }
+
+        if(event.key === 'Escape' && onEscape)
+        {
+            event.stopPropagation();
+            onEscape();
+            return;
+        }
+
+        if(event.key !== 'Tab') { return; }
+
+        const focusable = getFocusable(container.value);
+        if(focusable.length === 0)
+        {
+            event.preventDefault();
+            return;
+        }
+
+        const first = focusable[0];
+        const last = focusable[focusable.length - 1];
+        const activeEl = document.activeElement as HTMLElement | null;
+
+        if(event.shiftKey && (activeEl === first || !container.value.contains(activeEl)))
+        {
+            event.preventDefault();
+            last.focus();
+        }
+        else if(!event.shiftKey && (activeEl === last || !container.value.contains(activeEl)))
+        {
+            event.preventDefault();
+            first.focus();
+        }
+    }
+
+    watch(active, async (isActive) =>
+    {
+        if(isActive)
+        {
+            previouslyFocused = document.activeElement as HTMLElement | null;
+            document.addEventListener('keydown', handleKeydown, true);
+
+            // Wait a tick for the container to mount, then focus the first focusable.
+            //
+            // `preventScroll: true` is load-bearing here: if the container is mid-transition and
+            // sits off-screen (e.g. a drawer whose enter-from transform parks it outside the
+            // viewport), the browser will otherwise scroll the nearest scrollable ancestor to
+            // bring the focused element into view -- yanking the entire page sideways while the
+            // drawer slides in.
+            await nextTick();
+            if(container.value)
+            {
+                const focusable = getFocusable(container.value);
+                if(focusable.length > 0)
+                {
+                    focusable[0].focus({ preventScroll: true });
+                }
+                else
+                {
+                    container.value.focus({ preventScroll: true });
+                }
+            }
+        }
+        else
+        {
+            document.removeEventListener('keydown', handleKeydown, true);
+            if(previouslyFocused && typeof previouslyFocused.focus === 'function')
+            {
+                previouslyFocused.focus({ preventScroll: true });
+            }
+            previouslyFocused = null;
+        }
+    });
+}
+
+//----------------------------------------------------------------------------------------------------------------------