@webx-ui/core 0.6.0 → 0.8.0

package/dist/composables/useResponsiveShell.d.ts

@@ -0,0 +1,59 @@
+import { ComputedRef, Ref } from 'vue';
+/** What shape the navigation takes at the width it has been given. */
+export type ShellLayout = 'sidebar' | 'rail' | 'drawer';
+export interface ResponsiveShellOptions {
+    /** Under this width the menu leaves the page for a drawer behind a burger. */
+    phone?: number;
+    /** Under this width the sidebar starts as an icon rail. */
+    tablet?: number;
+    /** Whether it starts as a rail on a screen wide enough for the full sidebar. */
+    collapsed?: boolean;
+    /**
+     * Remembers a sidebar that was closed by hand, under this key in `localStorage`.
+     * Only the closing is kept: a sidebar left open goes back to following the width,
+     * so a desktop opens it and a tablet still starts with the rail.
+     */
+    persist?: string;
+}
+export interface ResponsiveShell {
+    /** Width of what is being measured, in pixels. `0` until it has been measured. */
+    width: Ref<number>;
+    layout: ComputedRef<ShellLayout>;
+    /** Hand this to `WxAside` and `WxMenu` — true for both the rail and the drawer. */
+    collapsed: ComputedRef<boolean>;
+    /** Whether there is room for a sidebar at all. False on a phone. */
+    showAside: ComputedRef<boolean>;
+    drawerOpen: Ref<boolean>;
+    /**
+     * What the one button in the header does: it collapses and expands the sidebar
+     * while the sidebar is on the page, and opens the drawer once the menu is gone.
+     * The icon follows `layout` — a burger belongs to the drawer alone.
+     */
+    toggle: () => void;
+    close: () => void;
+}
+/**
+ * The rule on its own, so it can be read — and tested — without a browser.
+ *
+ * `collapsed` is the answer to "is the sidebar a rail", and `null` leaves it to the
+ * width: a rail from the tablet breakpoint down. Only the phone breakpoint is
+ * absolute, because a menu that has nowhere to stand has to leave the page.
+ *
+ * A width of `0` means nothing has been measured yet: on the server, and on the very
+ * first render. The widest shape is the right guess there, since it is the one a
+ * desktop gets, and the measurement that follows corrects it before paint.
+ */
+export declare function shellLayoutFor(width: number, collapsed: boolean | null, options?: ResponsiveShellOptions): ShellLayout;
+/**
+ * Drives the three shapes an admin sidebar takes — full, icon rail, drawer — from
+ * the width of the shell rather than from the viewport's. The two are the same
+ * thing on a real page, and they are not inside a preview, a split screen or the
+ * demo box on this page, which is the case that catches a viewport media query out.
+ *
+ * ```ts
+ * const shell = useResponsiveShell(shellRef)
+ * ```
+ *
+ * Pass nothing to measure the page itself.
+ */
+export declare function useResponsiveShell(target?: Ref<HTMLElement | null | undefined>, options?: ResponsiveShellOptions): ResponsiveShell;

package/dist/index.d.ts

@@ -1,3 +1,6 @@
 export * from './components';
 export { WebxUI, type WebxUiOptions } from './plugin';
 export type { ControlSize, ControlStatus, ValidationErrors } from './composables/useFormField';
+export { useControlAttrs, type ControlAttrs } from './composables/useControlAttrs';
+export { useElementWidth } from './composables/useElementWidth';
+export { useResponsiveShell, shellLayoutFor, type ResponsiveShell, type ResponsiveShellOptions, type ShellLayout, } from './composables/useResponsiveShell';