@skewedaspect/sleekspace-ui 0.7.1 → 0.8.0

package/src/components/Page/SkPage.vue

@@ -1,22 +1,136 @@
+<!----------------------------------------------------------------------------------------------------------------------
+  - Page Component
+  --------------------------------------------------------------------------------------------------------------------->
+
 <template>
-    <div :class="classes" :style="customStyles" :data-scheme="theme">
+    <div ref="rootRef" :class="classes" :style="customStyles" :data-scheme="theme">
         <header v-if="$slots.header" class="sk-page-header">
             <slot name="header" />
         </header>
 
+        <div v-if="$slots.subheader" class="sk-page-subheader">
+            <slot name="subheader" />
+        </div>
+
         <div class="sk-page-main">
-            <aside v-if="$slots.sidebar" class="sk-page-sidebar">
-                <slot name="sidebar" />
+            <!-- Persistent (inline) sidebar on the left -->
+            <aside
+                v-if="hasSidebar && !isSidebarDrawerActive"
+                class="sk-page-sidebar"
+            >
+                <div v-if="$slots['sidebar-header']" class="sk-page-sidebar-header">
+                    <slot name="sidebar-header" :is-drawer="false" />
+                </div>
+                <div class="sk-page-sidebar-body">
+                    <slot name="sidebar" :is-drawer="false" />
+                </div>
+                <div v-if="$slots['sidebar-footer']" class="sk-page-sidebar-footer">
+                    <slot name="sidebar-footer" :is-drawer="false" />
+                </div>
             </aside>
 
-            <main class="sk-page-content">
-                <slot />
-            </main>
+            <div class="sk-page-center">
+                <div v-if="$slots['main-header']" class="sk-page-main-header">
+                    <slot name="main-header" />
+                </div>
+                <main class="sk-page-content">
+                    <slot />
+                </main>
+                <div v-if="$slots['main-footer']" class="sk-page-main-footer">
+                    <slot name="main-footer" />
+                </div>
+            </div>
+
+            <!-- Persistent (inline) aside on the right -->
+            <aside
+                v-if="hasAside && !isAsideDrawerActive"
+                class="sk-page-aside"
+            >
+                <div v-if="$slots['aside-header']" class="sk-page-aside-header">
+                    <slot name="aside-header" :is-drawer="false" />
+                </div>
+                <div class="sk-page-aside-body">
+                    <slot name="aside" :is-drawer="false" />
+                </div>
+                <div v-if="$slots['aside-footer']" class="sk-page-aside-footer">
+                    <slot name="aside-footer" :is-drawer="false" />
+                </div>
+            </aside>
         </div>
 
         <footer v-if="$slots.footer" class="sk-page-footer">
             <slot name="footer" />
         </footer>
+
+        <!-- Sidebar drawer (off-canvas, slides in from the left) -->
+        <template v-if="hasSidebar && isSidebarDrawerActive">
+            <Transition name="sk-page-drawer-backdrop">
+                <div
+                    v-if="sidebarDrawerOpen"
+                    class="sk-page-drawer-backdrop"
+                    :data-scheme="theme"
+                    @click="closeSidebarDrawer"
+                />
+            </Transition>
+
+            <Transition name="sk-page-drawer-left">
+                <aside
+                    v-if="sidebarDrawerOpen"
+                    ref="sidebarDrawerRef"
+                    class="sk-page-drawer sk-page-drawer-left"
+                    :data-scheme="theme"
+                    role="dialog"
+                    aria-modal="true"
+                    tabindex="-1"
+                    @click="onSidebarDrawerClick"
+                >
+                    <div v-if="$slots['sidebar-header']" class="sk-page-sidebar-header">
+                        <slot name="sidebar-header" :is-drawer="true" />
+                    </div>
+                    <div class="sk-page-sidebar-body">
+                        <slot name="sidebar" :is-drawer="true" />
+                    </div>
+                    <div v-if="$slots['sidebar-footer']" class="sk-page-sidebar-footer">
+                        <slot name="sidebar-footer" :is-drawer="true" />
+                    </div>
+                </aside>
+            </Transition>
+        </template>
+
+        <!-- Aside drawer (off-canvas, slides in from the right) -->
+        <template v-if="hasAside && isAsideDrawerActive">
+            <Transition name="sk-page-drawer-backdrop">
+                <div
+                    v-if="asideDrawerOpen"
+                    class="sk-page-drawer-backdrop"
+                    :data-scheme="theme"
+                    @click="closeAsideDrawer"
+                />
+            </Transition>
+
+            <Transition name="sk-page-drawer-right">
+                <aside
+                    v-if="asideDrawerOpen"
+                    ref="asideDrawerRef"
+                    class="sk-page-drawer sk-page-drawer-right"
+                    :data-scheme="theme"
+                    role="dialog"
+                    aria-modal="true"
+                    tabindex="-1"
+                    @click="onAsideDrawerClick"
+                >
+                    <div v-if="$slots['aside-header']" class="sk-page-aside-header">
+                        <slot name="aside-header" :is-drawer="true" />
+                    </div>
+                    <div class="sk-page-aside-body">
+                        <slot name="aside" :is-drawer="true" />
+                    </div>
+                    <div v-if="$slots['aside-footer']" class="sk-page-aside-footer">
+                        <slot name="aside-footer" :is-drawer="true" />
+                    </div>
+                </aside>
+            </Transition>
+        </template>
     </div>
 </template>
 
@@ -31,125 +145,404 @@
 <script setup lang="ts">
     /**
      * @component SkPage
-     * @description A full-page layout component that provides a structured application shell with header, sidebar,
-     * main content, and footer regions. Designed for building complete application pages with optional fixed
-     * positioning for header/footer and flexible sidebar placement. The layout automatically handles scrolling
-     * behavior and responsive spacing.
+     * @description Full-page layout shell with symmetric panels: a left sidebar and a right aside, each with
+     * its own header/body/footer slot trio, and each independently persistent, drawer-based, or responsive.
+     * Wraps header / subheader / main content (with optional `main-header` and `main-footer` strips) / footer.
+     * Sidebar slides in from the left; aside slides in from the right, with backdrop, focus trap, and
+     * ESC-to-close. Drop `<SkPageSidebarToggle />` into the navbar's `#leading` for the sidebar and
+     * `<SkPageSidebarToggle side="aside" />` into `#actions` for the aside.
      *
-     * @example
+     * @example App shell with both panels
      * ```vue
-     * <SkPage fixed-header sidebar-position="left" sidebar-width="280px">
+     * <SkPage fixed-header>
      *     <template #header>
-     *         <AppNavbar />
-     *     </template>
-     *     <template #sidebar>
-     *         <AppMenu />
+     *         <SkNavBar>
+     *             <template #leading><SkPageSidebarToggle /></template>
+     *             <template #brand>AppName</template>
+     *             <template #actions><SkPageSidebarToggle side="aside" /></template>
+     *         </SkNavBar>
      *     </template>
+     *     <template #sidebar><SkSidebar>...</SkSidebar></template>
+     *     <template #aside>...</template>
      *     <MainContent />
-     *     <template #footer>
-     *         <AppFooter />
-     *     </template>
      * </SkPage>
      * ```
      *
-     * @slot default - The main content area of the page. This is where your primary page content goes. Automatically
-     *                 handles scrolling when header/footer are fixed.
-     * @slot header - The page header region, typically used for navigation bars, branding, or page titles. Spans the
-     *                full width above the sidebar and content areas.
-     * @slot sidebar - Optional sidebar region for navigation menus, filters, or secondary content. Position is
-     *                 controlled by the `sidebarPosition` prop.
-     * @slot footer - The page footer region for copyright notices, links, or secondary navigation. Spans the full
-     *                width below the sidebar and content areas.
+     * @slot default - Main content. Scrolls inside the content area and receives the default content padding.
+     * @slot header - Top-of-page header. Typically a SkNavBar.
+     * @slot subheader - Full-width strip between the header and the main row. Good for breadcrumbs or sub-tabs.
+     * @slot sidebar - Left sidebar body. Renders inline when persistent, inside a drawer when in drawer mode.
+     *                 Slot props: `{ isDrawer: boolean }` — true when this invocation is the off-canvas drawer.
+     * @slot sidebar-header - Pinned top of the sidebar (e.g. logo, search). Renders in the drawer too.
+     *                        Slot props: `{ isDrawer: boolean }`.
+     * @slot sidebar-footer - Pinned bottom of the sidebar (e.g. user menu). Renders in the drawer too.
+     *                        Slot props: `{ isDrawer: boolean }`.
+     * @slot main-header - Pinned top of the center column (e.g. breadcrumbs, sub-tabs). Does not scroll.
+     * @slot main-footer - Pinned bottom of the center column (e.g. status bar). Does not scroll.
+     * @slot aside - Right aside body. Persistent or drawer, mirror of the sidebar on the opposite side.
+     *               Slot props: `{ isDrawer: boolean }` — use to add chrome only when rendering in the drawer.
+     * @slot aside-header - Pinned top of the aside (e.g. panel title). Renders in the drawer too.
+     *                      Slot props: `{ isDrawer: boolean }`.
+     * @slot aside-footer - Pinned bottom of the aside (e.g. action buttons). Renders in the drawer too.
+     *                      Slot props: `{ isDrawer: boolean }`.
+     * @slot footer - Bottom-of-page footer.
      */
 
-    import { computed, provide, watch } from 'vue';
+    import { type Ref, computed, onBeforeUnmount, onMounted, provide, ref, watch } from 'vue';
 
     // Types
     import type { SkThemeName } from '../Theme/types';
-    import type { SkPageSidebarPosition } from './types';
+    import type { SkPagePanelMode } from './types';
 
     // Composables
     import { provideTheme } from '../Theme/useTheme';
+    import { useFocusTrap } from '@/composables/useFocusTrap';
+    import { providePageDrawers } from '@/composables/usePageDrawer';
 
     //------------------------------------------------------------------------------------------------------------------
 
     export interface SkPageComponentProps
     {
         /**
-         * Controls which side of the page the sidebar appears on. The sidebar slot content
-         * will be positioned on the specified side, with the main content area filling the
-         * remaining space. Has no effect if the sidebar slot is not provided.
-         * @default 'left'
-         */
-        sidebarPosition ?: SkPageSidebarPosition;
-
-        /**
-         * When true, the header remains fixed at the top of the viewport while the main
-         * content scrolls beneath it. Useful for keeping navigation always accessible.
-         * The content area adjusts its top padding to prevent overlap with the fixed header.
+         * When true, the header remains sticky at the top of the viewport while the main content scrolls.
          * @default false
          */
         fixedHeader ?: boolean;
 
         /**
-         * When true, the footer remains fixed at the bottom of the viewport while the main
-         * content scrolls above it. Useful for persistent action bars or important links.
-         * The content area adjusts its bottom padding to prevent overlap with the fixed footer.
+         * When true, the footer remains sticky at the bottom of the viewport while the main content scrolls.
          * @default false
          */
         fixedFooter ?: boolean;
 
         /**
-         * Custom width for the sidebar region. Accepts any valid CSS width value (px, rem, %, etc.).
-         * When not specified, the sidebar uses the default width defined in the design tokens.
-         * Only applies when the sidebar slot is provided.
+         * Custom width for the sidebar (persistent and drawer). Accepts any CSS length. When not specified,
+         * uses the `--sk-page-sidebar-width` token default (16rem).
          */
         sidebarWidth ?: string;
 
         /**
-         * Optional theme name. When provided, SkPage acts as a theme provider — setting
-         * `data-scheme` on the root element and providing theme context for descendant
-         * components (including portal components like dropdowns and modals).
-         * When omitted, SkPage has no theme behavior.
+         * Custom width for the aside (persistent and drawer). Accepts any CSS length. When not specified,
+         * uses the `--sk-page-aside-width` token default (16rem).
+         */
+        asideWidth ?: string;
+
+        /**
+         * Sidebar rendering mode.
+         * - `auto`: persistent above `sidebarBreakpoint`, drawer below. Default.
+         * - `persistent`: always inline.
+         * - `drawer`: always off-canvas.
+         * @default 'auto'
+         */
+        sidebarMode ?: SkPagePanelMode;
+
+        /**
+         * Aside rendering mode. Mirror of `sidebarMode` for the right-side panel.
+         * @default 'auto'
+         */
+        asideMode ?: SkPagePanelMode;
+
+        /**
+         * Viewport width below which the sidebar's `auto` mode switches to drawer. Accepts any CSS length.
+         * @default '1024px'
+         */
+        sidebarBreakpoint ?: string;
+
+        /**
+         * Viewport width below which the aside's `auto` mode switches to drawer. Accepts any CSS length.
+         * @default '1024px'
+         */
+        asideBreakpoint ?: string;
+
+        /**
+         * Controlled sidebar drawer open state. Bind via `v-model:sidebarOpen` to control programmatically.
+         * When omitted, SkPage manages state internally.
+         */
+        sidebarOpen ?: boolean;
+
+        /**
+         * Controlled aside drawer open state. Bind via `v-model:asideOpen` to control programmatically.
+         * When omitted, SkPage manages state internally.
+         */
+        asideOpen ?: boolean;
+
+        /**
+         * Optional theme name. When provided, SkPage acts as a theme provider -- setting `data-scheme`
+         * on the root element and providing theme context for descendant components (including portal
+         * components like dropdowns and modals).
          */
         theme ?: SkThemeName;
+
+        /**
+         * When true, zeroes out `--sk-page-gap` and `--sk-page-content-padding` so panels and content
+         * sit flush against the header, footer, edges, and each other.
+         * @default false
+         */
+        flush ?: boolean;
     }
 
     //------------------------------------------------------------------------------------------------------------------
 
     const props = withDefaults(defineProps<SkPageComponentProps>(), {
-        sidebarPosition: 'left',
         fixedHeader: false,
         fixedFooter: false,
         sidebarWidth: undefined,
+        asideWidth: undefined,
+        sidebarMode: 'auto',
+        asideMode: 'auto',
+        sidebarBreakpoint: '1024px',
+        asideBreakpoint: '1024px',
+        sidebarOpen: undefined,
+        asideOpen: undefined,
         theme: undefined,
+        flush: false,
     });
 
+    const emit = defineEmits<{
+        'update:sidebarOpen' : [ value : boolean ];
+        'update:asideOpen' : [ value : boolean ];
+    }>();
+
+    const slots = defineSlots<{
+        'default' ?: () => unknown;
+        'header' ?: () => unknown;
+        'subheader' ?: () => unknown;
+        'sidebar' ?: (props : { isDrawer : boolean }) => unknown;
+        'sidebar-header' ?: (props : { isDrawer : boolean }) => unknown;
+        'sidebar-footer' ?: (props : { isDrawer : boolean }) => unknown;
+        'main-header' ?: () => unknown;
+        'main-footer' ?: () => unknown;
+        'aside' ?: (props : { isDrawer : boolean }) => unknown;
+        'aside-header' ?: (props : { isDrawer : boolean }) => unknown;
+        'aside-footer' ?: (props : { isDrawer : boolean }) => unknown;
+        'footer' ?: () => unknown;
+    }>();
+
     //------------------------------------------------------------------------------------------------------------------
-    // Classes
+    // Slot-derived state
     //------------------------------------------------------------------------------------------------------------------
 
-    const classes = computed(() => ({
-        'sk-page': true,
-        [`sk-sidebar-${ props.sidebarPosition }`]: true,
-        'sk-fixed-header': props.fixedHeader,
-        'sk-fixed-footer': props.fixedFooter,
-    }));
+    const hasSidebar = computed<boolean>(() => Boolean(slots.sidebar));
+    const hasAside = computed<boolean>(() => Boolean(slots.aside));
 
     //------------------------------------------------------------------------------------------------------------------
-    // Custom Styles
+    // Responsive mode detection — driven by SkPage's own width, not the viewport, so embedded
+    // demos, split panes, and modal shells collapse based on the space they're actually given.
     //------------------------------------------------------------------------------------------------------------------
 
-    const customStyles = computed(() =>
+    const rootRef = ref<HTMLElement | null>(null);
+    const rootWidth = ref<number>(Number.POSITIVE_INFINITY);
+
+    function resolvePx(value : string, context : HTMLElement | null) : number
+    {
+        // Fast path for plain pixel values.
+        if(/^\d+(\.\d+)?px$/.test(value)) { return parseFloat(value); }
+
+        if(typeof document === 'undefined') { return parseFloat(value) || 1024; }
+
+        // Measure by writing the length into a detached element and reading its computed width.
+        // Handles rem, em, vw, ch, etc. in a single mechanism.
+        const probe = document.createElement('div');
+        probe.style.position = 'absolute';
+        probe.style.visibility = 'hidden';
+        probe.style.pointerEvents = 'none';
+        probe.style.width = value;
+        (context ?? document.body).appendChild(probe);
+        const px = probe.offsetWidth;
+        probe.remove();
+        return px;
+    }
+
+    const sidebarBreakpointPx = computed<number>(() => resolvePx(props.sidebarBreakpoint, rootRef.value));
+    const asideBreakpointPx = computed<number>(() => resolvePx(props.asideBreakpoint, rootRef.value));
+
+    const sidebarBelowBreakpoint = computed<boolean>(() => rootWidth.value < sidebarBreakpointPx.value);
+    const asideBelowBreakpoint = computed<boolean>(() => rootWidth.value < asideBreakpointPx.value);
+
+    let observer : ResizeObserver | null = null;
+
+    onMounted(() =>
+    {
+        if(!rootRef.value || typeof ResizeObserver === 'undefined') { return; }
+
+        rootWidth.value = rootRef.value.clientWidth;
+
+        observer = new ResizeObserver((entries) =>
+        {
+            for(const entry of entries)
+            {
+                // borderBoxSize is the standards-aligned readout; fall back to contentRect for older engines.
+                const size = entry.borderBoxSize?.[0];
+                rootWidth.value = size ? size.inlineSize : entry.contentRect.width;
+            }
+        });
+        observer.observe(rootRef.value);
+    });
+
+    onBeforeUnmount(() =>
+    {
+        observer?.disconnect();
+        observer = null;
+    });
+
+    const isSidebarDrawerActive = computed<boolean>(() =>
+    {
+        if(!hasSidebar.value) { return false; }
+        if(props.sidebarMode === 'drawer') { return true; }
+        if(props.sidebarMode === 'persistent') { return false; }
+        return sidebarBelowBreakpoint.value;
+    });
+
+    const isAsideDrawerActive = computed<boolean>(() =>
+    {
+        if(!hasAside.value) { return false; }
+        if(props.asideMode === 'drawer') { return true; }
+        if(props.asideMode === 'persistent') { return false; }
+        return asideBelowBreakpoint.value;
+    });
+
+    //------------------------------------------------------------------------------------------------------------------
+    // Drawer open state (uncontrolled by default, controlled when the corresponding v-model is bound)
+    //------------------------------------------------------------------------------------------------------------------
+
+    interface DrawerState
+    {
+        open : Ref<boolean>;
+        setOpen : (value : boolean) => void;
+    }
+
+    function useDrawerState(
+        controlledProp : () => boolean | undefined,
+        setControlled : (value : boolean) => void,
+        isActive : Ref<boolean>
+    ) : DrawerState
     {
-        if(!props.sidebarWidth)
+        const internal = ref<boolean>(false);
+        const isControlled = computed<boolean>(() => controlledProp() !== undefined);
+
+        const open = computed<boolean>(() =>
         {
-            return {};
-        }
+            if(!isActive.value) { return false; }
+            if(isControlled.value) { return controlledProp() === true; }
+            return internal.value;
+        });
 
-        return {
-            '--sk-page-sidebar-width': props.sidebarWidth,
+        const setOpen = (value : boolean) : void =>
+        {
+            if(!isControlled.value) { internal.value = value; }
+            setControlled(value);
         };
+
+        // Collapse open state if layout becomes persistent (e.g. user widens the viewport).
+        watch(isActive, (active) =>
+        {
+            if(!active && open.value) { setOpen(false); }
+        });
+
+        return { open, setOpen };
+    }
+
+    const sidebar = useDrawerState(
+        () => props.sidebarOpen,
+        (value) => emit('update:sidebarOpen', value),
+        isSidebarDrawerActive
+    );
+    const aside = useDrawerState(
+        () => props.asideOpen,
+        (value) => emit('update:asideOpen', value),
+        isAsideDrawerActive
+    );
+
+    const sidebarDrawerOpen = sidebar.open;
+    const asideDrawerOpen = aside.open;
+
+    const closeSidebarDrawer = () : void => sidebar.setOpen(false);
+    const closeAsideDrawer = () : void => aside.setOpen(false);
+
+    //------------------------------------------------------------------------------------------------------------------
+    // Click-to-dismiss on empty drawer chrome. We don't use `pointer-events: none` for this
+    // because that also blocks wheel/touch scrolling inside the drawer body. Instead we listen
+    // for clicks on the drawer and close when the target wasn't something interactive.
+    //------------------------------------------------------------------------------------------------------------------
+
+    const INTERACTIVE_SELECTOR = [
+        'a[href]',
+        'button:not([disabled])',
+        'input:not([disabled]):not([type="hidden"])',
+        'select:not([disabled])',
+        'textarea:not([disabled])',
+        'label',
+        'summary',
+        '[role="button"]',
+        '[role="link"]',
+        '[role="menuitem"]',
+        '[role="option"]',
+        '[role="tab"]',
+        '[role="checkbox"]',
+        '[role="radio"]',
+        '[role="switch"]',
+        '[tabindex]:not([tabindex="-1"])',
+        '.sk-sidebar-item',
+    ].join(',');
+
+    function onSidebarDrawerClick(event : MouseEvent) : void
+    {
+        const target = event.target as HTMLElement | null;
+        if(!target || !target.closest(INTERACTIVE_SELECTOR)) { closeSidebarDrawer(); }
+    }
+
+    function onAsideDrawerClick(event : MouseEvent) : void
+    {
+        const target = event.target as HTMLElement | null;
+        if(!target || !target.closest(INTERACTIVE_SELECTOR)) { closeAsideDrawer(); }
+    }
+
+    //------------------------------------------------------------------------------------------------------------------
+    // Provide drawer context for toggle components
+    //------------------------------------------------------------------------------------------------------------------
+
+    providePageDrawers(
+        { isOpen: sidebarDrawerOpen, isAvailable: isSidebarDrawerActive, setOpen: sidebar.setOpen },
+        { isOpen: asideDrawerOpen, isAvailable: isAsideDrawerActive, setOpen: aside.setOpen }
+    );
+
+    //------------------------------------------------------------------------------------------------------------------
+    // Focus trap
+    //------------------------------------------------------------------------------------------------------------------
+
+    const sidebarDrawerRef = ref<HTMLElement | null>(null);
+    const asideDrawerRef = ref<HTMLElement | null>(null);
+
+    useFocusTrap({
+        active: sidebarDrawerOpen,
+        container: sidebarDrawerRef,
+        onEscape: closeSidebarDrawer,
+    });
+    useFocusTrap({
+        active: asideDrawerOpen,
+        container: asideDrawerRef,
+        onEscape: closeAsideDrawer,
+    });
+
+    //------------------------------------------------------------------------------------------------------------------
+    // Classes & styles
+    //------------------------------------------------------------------------------------------------------------------
+
+    const classes = computed(() => ({
+        'sk-page': true,
+        'sk-fixed-header': props.fixedHeader,
+        'sk-fixed-footer': props.fixedFooter,
+        'sk-sidebar-drawer-active': isSidebarDrawerActive.value,
+        'sk-aside-drawer-active': isAsideDrawerActive.value,
+        'sk-flush': props.flush,
+    }));
+
+    const customStyles = computed(() =>
+    {
+        const styles : Record<string, string> = {};
+        if(props.sidebarWidth) { styles['--sk-page-sidebar-width'] = props.sidebarWidth; }
+        if(props.asideWidth) { styles['--sk-page-aside-width'] = props.asideWidth; }
+        return styles;
     });
 
     //------------------------------------------------------------------------------------------------------------------
@@ -159,19 +552,14 @@
     if(props.theme)
     {
         const { currentTheme, setTheme } = provideTheme(props.theme);
-
-        // Provide theme for portal components (dropdown, modal, tooltip, etc.)
         provide('sk-theme', currentTheme);
 
-        // Watch for external theme prop changes
         watch(() => props.theme, (newTheme) =>
         {
-            if(newTheme)
-            {
-                setTheme(newTheme);
-            }
+            if(newTheme) { setTheme(newTheme); }
         });
     }
+
 </script>
 
 <!--------------------------------------------------------------------------------------------------------------------->