@ainsleydev/sveltekit-helper 0.1.5 → 0.2.0

package/README.md

@@ -11,6 +11,7 @@ pnpm add @ainsleydev/sveltekit-helper
 ## Features
 
 - **Grid System**: Responsive Container, Row, and Column components with CSS variables
+- **Navigation Components**: Mobile-first Sidebar and Hamburger menu components
 - **Form Utilities**: Schema generation and error helpers for Zod validation
 - **Payload CMS Integration**: Ready-to-use components for Payload CMS forms and media
 - **SCSS with BEM**: All components use SCSS with BEM naming convention
@@ -29,7 +30,7 @@ All Grid components use CSS variables with fallback values, allowing flexible cu
 
 **Responsive Variables:**
 
-Row and Column components include mobile-specific overrides (< 568px). You can customize responsive behavior using:
+Row and Column components include mobile-specific overrides (< 568px). You can customise responsive behaviour using:
 
 ```css
 :root {
@@ -157,6 +158,128 @@ Base column component with customisable gap. Consumers should define their own g
 }
 ```
 
+## Navigation Components
+
+### Sidebar
+
+Mobile-first sidebar navigation component with toggle and hamburger display modes. Automatically collapses on mobile and remains visible on desktop.
+
+```svelte
+<script>
+	import { Sidebar } from '@ainsleydev/sveltekit-helper/components'
+</script>
+
+<Sidebar bind:isOpen>
+	<nav>
+		<a href="/">Home</a>
+		<a href="/about">About</a>
+		<a href="/contact">Contact</a>
+	</nav>
+</Sidebar>
+```
+
+#### Props
+
+- `menuLabel?: string` - Label for toggle button (default: 'Menu')
+- `isOpen?: boolean` - Bindable open/closed state
+- `position?: 'left' | 'right'` - Sidebar position (default: 'left')
+- `width?: string` - Sidebar width on mobile (default: '50vw')
+- `top?: number` - Sticky position offset on desktop (default: 160)
+- `closeOnOverlayClick?: boolean` - Close when overlay is clicked (default: true)
+- `overlayOpacity?: number` - Overlay opacity when open (default: 0.3)
+- `toggleStyle?: 'toggle' | 'hamburger'` - Toggle display mode (default: 'toggle')
+- `class?: string` - Additional CSS classes
+- `onOpen?: () => void` - Callback when sidebar opens
+- `onClose?: () => void` - Callback when sidebar closes
+- `onToggle?: (isOpen: boolean) => void` - Callback when sidebar toggles
+
+#### Examples
+
+With hamburger menu:
+
+```svelte
+<Sidebar toggleStyle="hamburger" bind:isOpen>
+	<nav>...</nav>
+</Sidebar>
+```
+
+Right-side with custom width:
+
+```svelte
+<Sidebar position="right" width="300px">
+	<nav>...</nav>
+</Sidebar>
+```
+
+#### Customisation
+
+Override CSS variables globally from `:root`:
+
+```css
+:root {
+	--sidebar-width: 400px;
+	--sidebar-min-width: 300px;
+	--sidebar-background: #1a1a1a;
+	--sidebar-border-colour: rgba(255, 255, 255, 0.2);
+	--sidebar-overlay-colour: #000;
+	--sidebar-overlay-opacity: 0.5;
+
+	/* Toggle button */
+	--sidebar-toggle-background: #2a2a2a;
+	--sidebar-toggle-colour: #fff;
+	--sidebar-toggle-padding: 0.5rem 1.5rem;
+	--sidebar-toggle-radius: 8px;
+	--sidebar-toggle-font-size: 1rem;
+
+	/* Inner spacing */
+	--sidebar-inner-padding: 2rem 2rem 0 2rem;
+}
+```
+
+Or use inline styles:
+
+```svelte
+<Sidebar style="--sidebar-background: #2a2a2a; --sidebar-width: 400px">
+	<nav>...</nav>
+</Sidebar>
+```
+
+### Hamburger
+
+Hamburger menu icon with animation for mobile navigation. Uses `svelte-hamburgers` under the hood.
+
+```svelte
+<script>
+	import { Hamburger } from '@ainsleydev/sveltekit-helper/components'
+
+	let isOpen = $state(false)
+</script>
+
+<Hamburger bind:isOpen />
+```
+
+#### Props
+
+- `isOpen?: boolean` - Bindable open/closed state
+- `gap?: string` - Distance from top/right edges (default: '0.8rem')
+- `class?: string` - Additional CSS classes
+- `ariaLabel?: string` - Accessibility label (default: 'Toggle menu')
+- `onChange?: (isOpen: boolean) => void` - Callback when state changes
+
+#### Customisation
+
+```css
+:root {
+	--hamburger-gap: 1rem;
+	--hamburger-z-index: 10000;
+	--hamburger-colour: #fff;
+	--hamburger-layer-width: 28px;
+	--hamburger-layer-height: 3px;
+	--hamburger-layer-spacing: 6px;
+	--hamburger-border-radius: 3px;
+}
+```
+
 ## Form Utilities
 
 ### generateFormSchema

package/dist/components/Hamburger.svelte

@@ -0,0 +1,62 @@
+<script lang="ts" module>
+import type { HamburgerType as HamburgerTypeLib } from 'svelte-hamburgers';
+
+export type HamburgerType = HamburgerTypeLib;
+
+export type HamburgerProps = {
+	// See: https://github.com/ghostdevv/svelte-hamburgers/blob/main/types.md
+	style?: HamburgerType;
+	isOpen?: boolean;
+	gap?: string;
+	class?: string;
+	onChange?: (isOpen: boolean) => void;
+};
+</script>
+
+<script lang="ts">
+	import { Hamburger as SvelteHamburger } from 'svelte-hamburgers';
+
+	let {
+		style = 'spin',
+		isOpen = $bindable(false),
+		gap = '0.8rem',
+		class: className = '',
+		onChange
+	}: HamburgerProps = $props();
+</script>
+
+<!--
+	@component
+
+	Hamburger menu icon with animation for mobile navigation.
+	Uses svelte-hamburgers under the hood.
+
+	@example
+	```svelte
+	<Hamburger bind:isOpen />
+	```
+
+	@example
+	```svelte
+	<Hamburger gap="1rem">
+	```
+-->
+<div class="hamburger-wrapper {className}" style="--hamburger-gap: {gap}" aria-label="Toggle Menu">
+	<SvelteHamburger
+		type={style}
+		bind:open={isOpen}
+		on:change={() => onChange?.(isOpen)}
+		--color="var(--hamburger-colour, var(--colour-base-light))"
+		--layer-width="var(--hamburger-layer-width, 24px)"
+		--layer-height="var(--hamburger-layer-height, 2px)"
+		--layer-spacing="var(--hamburger-layer-spacing, 5px)"
+		--border-radius="var(--hamburger-border-radius, 2px)"
+	/>
+</div>
+
+<style>.hamburger-wrapper {
+  position: fixed;
+  top: var(--hamburger-gap, 0.8rem);
+  right: var(--hamburger-gap, 0.8rem);
+  z-index: var(--hamburger-z-index, 10000);
+}</style>

package/dist/components/Hamburger.svelte.d.ts

@@ -0,0 +1,27 @@
+import type { HamburgerType as HamburgerTypeLib } from 'svelte-hamburgers';
+export type HamburgerType = HamburgerTypeLib;
+export type HamburgerProps = {
+    style?: HamburgerType;
+    isOpen?: boolean;
+    gap?: string;
+    class?: string;
+    onChange?: (isOpen: boolean) => void;
+};
+/**
+ * Hamburger menu icon with animation for mobile navigation.
+ * Uses svelte-hamburgers under the hood.
+ *
+ * @example
+ * ```svelte
+ * <Hamburger bind:isOpen />
+ * ```
+ *
+ * @example
+ * ```svelte
+ * <Hamburger gap="1rem">
+ * ```
+ */
+declare const Hamburger: import("svelte").Component<HamburgerProps, {}, "isOpen">;
+type Hamburger = ReturnType<typeof Hamburger>;
+export default Hamburger;
+//# sourceMappingURL=Hamburger.svelte.d.ts.map

package/dist/components/Hamburger.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Hamburger.svelte.d.ts","sourceRoot":"","sources":["../../src/components/Hamburger.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,IAAI,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAE3E,MAAM,MAAM,aAAa,GAAG,gBAAgB,CAAC;AAE7C,MAAM,MAAM,cAAc,GAAG;IAE5B,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;CACrC,CAAC;AA4BF;;;;;;;;;;;;;GAaG;AACH,QAAA,MAAM,SAAS,0DAAwC,CAAC;AACxD,KAAK,SAAS,GAAG,UAAU,CAAC,OAAO,SAAS,CAAC,CAAC;AAC9C,eAAe,SAAS,CAAC"}

package/dist/components/Sidebar.svelte

@@ -0,0 +1,274 @@
+<script lang="ts" module>
+import type { Snippet } from 'svelte';
+
+export type SidebarProps = {
+	menuLabel?: string;
+	children: Snippet;
+	isOpen?: boolean;
+	position?: 'left' | 'right';
+	width?: string;
+	top?: number;
+	closeOnOverlayClick?: boolean;
+	overlayOpacity?: number;
+	toggleStyle?: 'toggle' | 'hamburger';
+	class?: string;
+	onOpen?: () => void;
+	onClose?: () => void;
+	onToggle?: (isOpen: boolean) => void;
+};
+</script>
+
+<script lang="ts">
+	import { onMount } from 'svelte';
+	import Hamburger from './Hamburger.svelte';
+
+	let {
+		menuLabel = 'Menu',
+		children,
+		isOpen = $bindable(false),
+		position = 'left',
+		width = '50vw',
+		top = 160,
+		closeOnOverlayClick = true,
+		overlayOpacity = 0.3,
+		toggleStyle = 'toggle',
+		class: className = '',
+		onOpen,
+		onClose,
+		onToggle
+	}: SidebarProps = $props();
+
+	const uniqueId = `sidebar-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
+	let checkboxRef = $state<HTMLInputElement>();
+	let overlayRef = $state<HTMLLabelElement>();
+	let contentRef = $state<HTMLDivElement>();
+	let previousActiveElement = $state<HTMLElement>();
+
+	// Sync checkbox with isOpen state.
+	$effect(() => {
+		if (checkboxRef && checkboxRef.checked !== isOpen) {
+			checkboxRef.checked = isOpen;
+		}
+	});
+
+	// Watch for changes to isOpen and call callbacks.
+	$effect(() => {
+		if (isOpen) {
+			onOpen?.();
+		} else {
+			onClose?.();
+		}
+		onToggle?.(isOpen);
+	});
+
+	// Focus management.
+	$effect(() => {
+		if (isOpen && contentRef) {
+			previousActiveElement = document.activeElement as HTMLElement;
+			const firstFocusable = contentRef.querySelector<HTMLElement>(
+				'a, button, input, textarea, select, [tabindex]:not([tabindex="-1"])'
+			);
+			firstFocusable?.focus();
+		} else if (!isOpen && previousActiveElement) {
+			previousActiveElement.focus();
+			previousActiveElement = undefined;
+		}
+	});
+
+	onMount(() => {
+		// Capture refs in local variables to ensure proper cleanup.
+		const overlay = overlayRef;
+		const checkbox = checkboxRef;
+
+		if (!overlay || !checkbox) return;
+
+		const handleOverlayClick = (e: Event) => {
+			if (!closeOnOverlayClick) return;
+			e.preventDefault();
+			checkbox.checked = false;
+			isOpen = false;
+		};
+
+		const handleCheckboxChange = () => {
+			isOpen = checkbox.checked;
+		};
+
+		const handleKeydown = (e: KeyboardEvent) => {
+			if (e.key === 'Escape' && isOpen) {
+				e.preventDefault();
+				checkbox.checked = false;
+				isOpen = false;
+			}
+		};
+
+		overlay.addEventListener('click', handleOverlayClick);
+		checkbox.addEventListener('change', handleCheckboxChange);
+		document.addEventListener('keydown', handleKeydown);
+
+		return () => {
+			overlay.removeEventListener('click', handleOverlayClick);
+			checkbox.removeEventListener('change', handleCheckboxChange);
+			document.removeEventListener('keydown', handleKeydown);
+		};
+	});
+</script>
+
+<!--
+	@component
+
+	Mobile-first sidebar navigation component with toggle and hamburger options.
+	Automatically collapses on mobile and remains visible on desktop.
+
+	@example
+	```svelte
+	<Sidebar bind:isOpen>
+		<nav>
+			<a href="/">Home</a>
+			<a href="/about">About</a>
+		</nav>
+	</Sidebar>
+	```
+
+	@example
+	```svelte
+	<Sidebar toggleStyle="hamburger" position="right" width="300px">
+		<nav>...</nav>
+	</Sidebar>
+	```
+-->
+<aside
+	class="sidebar sidebar--{toggleStyle} sidebar--{position} {className}"
+	style="--sidebar-width: {width}; --sidebar-top: {top}px; --sidebar-overlay-opacity: {overlayOpacity}"
+>
+	<!-- Click Logic -->
+	<input
+		bind:this={checkboxRef}
+		type="checkbox"
+		class="sidebar__checkbox"
+		id={uniqueId}
+		aria-label={menuLabel}
+	/>
+	<label bind:this={overlayRef} for={uniqueId} class="sidebar__overlay"></label>
+	<!-- Hamburger -->
+	{#if toggleStyle === 'hamburger'}
+		<Hamburger bind:isOpen />
+	{/if}
+	<!-- Content -->
+	<div bind:this={contentRef} class="sidebar__content" role="navigation" aria-label={menuLabel}>
+		{#if toggleStyle === 'toggle'}
+			<label for={uniqueId} class="sidebar__toggle">
+				{menuLabel}
+			</label>
+		{/if}
+		<div class="sidebar__inner">
+			{@render children()}
+		</div>
+	</div>
+</aside>
+
+<style>.sidebar__toggle {
+  position: absolute;
+  display: none;
+  bottom: 0;
+  right: 1px;
+  background-color: var(--sidebar-toggle-background, var(--colour-base-black));
+  color: var(--sidebar-toggle-colour, var(--colour-base-light));
+  padding: var(--sidebar-toggle-padding, 0.25rem 1.5rem);
+  border-top-right-radius: var(--sidebar-toggle-radius, 0.375rem);
+  border-top-left-radius: var(--sidebar-toggle-radius, 0.375rem);
+  font-size: var(--sidebar-toggle-font-size, 0.9rem);
+  transform: rotate(90deg) translate(0%, -100%);
+  transform-origin: right top;
+  cursor: pointer;
+  user-select: none;
+  transition: box-shadow 200ms linear;
+  border: 1px solid var(--sidebar-border-colour, rgba(255, 255, 255, 0.1));
+}
+.sidebar__toggle::before {
+  content: "";
+  position: absolute;
+  top: calc(90% + 2px);
+  left: 1px;
+  width: calc(100% - 2px);
+  height: 10%;
+  background: var(--sidebar-toggle-background, var(--colour-base-black));
+}
+.sidebar__overlay {
+  position: fixed;
+  top: 0;
+  left: 0;
+  width: 100%;
+  height: 100%;
+  background-color: var(--sidebar-overlay-colour, var(--colour-grey-900));
+  z-index: -100;
+  opacity: 0;
+  transition: opacity 400ms ease, z-index 400ms step-end;
+}
+.sidebar__checkbox {
+  position: fixed;
+  top: 0;
+  display: none;
+}
+.sidebar__checkbox:checked ~ .sidebar__content {
+  translate: 0;
+  z-index: 9999999;
+}
+.sidebar__checkbox:checked ~ .sidebar__content .sidebar__toggle {
+  box-shadow: none;
+}
+.sidebar__checkbox:checked ~ .sidebar__overlay {
+  transition: opacity 600ms ease, z-index 600ms step-start;
+  opacity: var(--sidebar-overlay-opacity, 0.3);
+  z-index: 999999;
+}
+@media (max-width: 1023px) {
+  .sidebar__content {
+    position: fixed;
+    display: grid;
+    top: 0;
+    height: 100%;
+    width: var(--sidebar-width, 50vw);
+    min-width: var(--sidebar-min-width, 270px);
+    background-color: var(--sidebar-background, var(--colour-base-black));
+    border-color: var(--sidebar-border-colour, rgba(255, 255, 255, 0.1));
+    z-index: 1000;
+    transition: translate 600ms cubic-bezier(0.1, 0.7, 0.1, 1);
+  }
+  .sidebar__inner {
+    overflow: auto;
+    display: flex;
+    flex-direction: column;
+    padding: var(--sidebar-inner-padding, 2rem 1.8rem 0 1.8rem);
+  }
+  .sidebar__toggle {
+    display: flex;
+  }
+}
+@media (min-width: 1024px) {
+  .sidebar {
+    position: sticky;
+    top: var(--sidebar-top, 160px);
+  }
+  .sidebar__overlay {
+    display: none;
+  }
+}
+@media (max-width: 1023px) {
+  .sidebar--left .sidebar__content {
+    left: 0;
+    border-right-style: solid;
+    border-right-width: 1px;
+    translate: -100%;
+  }
+}
+@media (max-width: 1023px) {
+  .sidebar--right .sidebar__content {
+    right: 0;
+    border-left-style: solid;
+    border-left-width: 1px;
+    translate: 100%;
+  }
+}
+.sidebar--hamburger .sidebar__toggle {
+  display: none;
+}</style>

package/dist/components/Sidebar.svelte.d.ts

@@ -0,0 +1,41 @@
+import type { Snippet } from 'svelte';
+export type SidebarProps = {
+    menuLabel?: string;
+    children: Snippet;
+    isOpen?: boolean;
+    position?: 'left' | 'right';
+    width?: string;
+    top?: number;
+    closeOnOverlayClick?: boolean;
+    overlayOpacity?: number;
+    toggleStyle?: 'toggle' | 'hamburger';
+    class?: string;
+    onOpen?: () => void;
+    onClose?: () => void;
+    onToggle?: (isOpen: boolean) => void;
+};
+/**
+ * Mobile-first sidebar navigation component with toggle and hamburger options.
+ * Automatically collapses on mobile and remains visible on desktop.
+ *
+ * @example
+ * ```svelte
+ * <Sidebar bind:isOpen>
+ * 	<nav>
+ * 		<a href="/">Home</a>
+ * 		<a href="/about">About</a>
+ * 	</nav>
+ * </Sidebar>
+ * ```
+ *
+ * @example
+ * ```svelte
+ * <Sidebar toggleStyle="hamburger" position="right" width="300px">
+ * 	<nav>...</nav>
+ * </Sidebar>
+ * ```
+ */
+declare const Sidebar: import("svelte").Component<SidebarProps, {}, "isOpen">;
+type Sidebar = ReturnType<typeof Sidebar>;
+export default Sidebar;
+//# sourceMappingURL=Sidebar.svelte.d.ts.map

package/dist/components/Sidebar.svelte.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Sidebar.svelte.d.ts","sourceRoot":"","sources":["../../src/components/Sidebar.svelte.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC;AAEtC,MAAM,MAAM,YAAY,GAAG;IAC1B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC5B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,mBAAmB,CAAC,EAAE,OAAO,CAAC;IAC9B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,CAAC,EAAE,QAAQ,GAAG,WAAW,CAAC;IACrC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IACrB,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;CACrC,CAAC;AAiIF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,QAAA,MAAM,OAAO,wDAAwC,CAAC;AACtD,KAAK,OAAO,GAAG,UAAU,CAAC,OAAO,OAAO,CAAC,CAAC;AAC1C,eAAe,OAAO,CAAC"}

package/dist/components/index.d.ts

@@ -0,0 +1,3 @@
+export { default as Sidebar } from './Sidebar.svelte';
+export { default as Hamburger } from './Hamburger.svelte';
+//# sourceMappingURL=index.d.ts.map

package/dist/components/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/components/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,IAAI,OAAO,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,OAAO,IAAI,SAAS,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/components/index.js

@@ -0,0 +1,2 @@
+export { default as Sidebar } from './Sidebar.svelte';
+export { default as Hamburger } from './Hamburger.svelte';

package/dist/index.d.ts

@@ -4,6 +4,7 @@
  * SvelteKit utilities, components and helpers for ainsley.dev builds.
  * Provides form utilities, grid components, and Payload CMS integrations.
  */
+export * from './components/index.js';
 export * from './components/Grid/index.js';
 export * from './components/payload/index.js';
 export * from './utils/forms/index.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,cAAc,4BAA4B,CAAC;AAC3C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,wBAAwB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,cAAc,uBAAuB,CAAC;AACtC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,+BAA+B,CAAC;AAC9C,cAAc,wBAAwB,CAAC"}

package/dist/index.js

@@ -5,6 +5,7 @@
  * Provides form utilities, grid components, and Payload CMS integrations.
  */
 // Re-export all exports from submodules
+export * from './components/index.js';
 export * from './components/Grid/index.js';
 export * from './components/payload/index.js';
 export * from './utils/forms/index.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ainsleydev/sveltekit-helper",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "description": "SvelteKit utilities, components and helpers for ainsley.dev builds",
   "license": "MIT",
   "type": "module",
@@ -29,6 +29,11 @@
       "svelte": "./dist/index.js",
       "default": "./dist/index.js"
     },
+    "./components": {
+      "types": "./dist/components/index.d.ts",
+      "svelte": "./dist/components/index.js",
+      "default": "./dist/components/index.js"
+    },
     "./components/Grid": {
       "types": "./dist/components/Grid/index.d.ts",
       "svelte": "./dist/components/Grid/index.js",
@@ -67,7 +72,9 @@
       "optional": true
     }
   },
-  "dependencies": {},
+  "dependencies": {
+    "svelte-hamburgers": "^4.1.0"
+  },
   "devDependencies": {
     "@sveltejs/kit": "^2.0.0",
     "@sveltejs/package": "^2.0.0",