mapcn-svelte

The mapcn-svelte sidebar package provides a comprehensive set of Svelte components for building complex sidebar layouts. The library uses a provider-based pattern where a SidebarProvider (or Sidebar) manages the state, and various sub-components like SidebarContent, SidebarHeader, SidebarFooter, and SidebarMenu are used to structure the UI.

Key components include:

• Layout Containers: Sidebar (Root), SidebarContent, SidebarHeader, SidebarFooter, SidebarInset, and SidebarRail.
• Menu System: SidebarMenu, SidebarMenuItem, SidebarMenuButton, SidebarMenuBadge, and nested structures like SidebarMenuSub.
• Grouping: SidebarGroup, SidebarGroupLabel, SidebarGroupContent, and SidebarGroupAction.
• Controls: SidebarTrigger for toggling sidebar state and useSidebar for accessing the sidebar context.

Note: Many components are exported with both their original names and prefixed with Sidebar (e.g., Root is exported as both Root and Sidebar) to allow for flexible importing.

import {
  Sidebar,
  SidebarContent,
  SidebarHeader,
  SidebarFooter,
  SidebarTrigger,
  SidebarMenu,
  SidebarMenuItem,
  SidebarMenuButton
} from "./sidebar";

// Example structure
<Sidebar>
  <SidebarHeader>Header Content</SidebarHeader>
  <SidebarContent>
    <SidebarMenu>
      <SidebarMenuItem>
        <SidebarMenuButton>Menu Item</SidebarMenuButton>
      </SidebarMenuItem>
    </SidebarMenu>
  </SidebarContent>
  <SidebarFooter>Footer Content</SidebarFooter>
  <SidebarTrigger />
</Sidebar>

The mapConfig object defines the visual and spatial parameters for a choropleth map block. It includes:

• view: Controls the initial map state with center (an array of [longitude, latitude]), zoom, and zoom constraints (minZoom, maxZoom).
• scaleStops: An array of numeric thresholds used to map data values to the color ramp.
• colors: A theme-based configuration supporting both light and dark modes. Each theme defines:
  • base: The fill color for countries with no data (value 0).
  • ramp: A sequential array of four color strings mapped to the scaleStops.
  • hover: The fill color applied when a country is hovered.

export const mapConfig = {
	view: {
		center: [12, 28] as [number, number],
		zoom: 1.4,
		minZoom: 1,
		maxZoom: 4,
	},
	scaleStops: [0, 25, 50, 75, 100] as const,
	colors: {
		light: {
			base: "#f0f0f0",
			ramp: ["#d4d4d4", "#a3a3a3", "#737373", "#404040"],
			hover: "#0a0a0a",
		},
		dark: {
			base: "#2a2a2a",
			ramp: ["#404040", "#737373", "#a3a3a3", "#d4d4d4"],
			hover: "#ffffff",
		},
	},
};

The CommandDialog component provides a searchable command palette interface wrapped in a dialog. It combines bits-ui Dialog and Command primitives to allow users to search for and execute commands within a modal overlay.

Key features:

• Two-way binding: Use bind:open to control visibility and bind:value to track the current search input.
• Accessibility: Includes a visually hidden (screen-reader only) header containing a title and description for compliance with dialog accessibility standards.
• Customization: Accepts portalProps to control where the dialog is rendered in the DOM and restProps to pass through standard Dialog and Command primitive attributes.

<script>
  import CommandDialog from "$lib/registry/ui/command/command-dialog.svelte";

  let open = $state(false);
  let value = $state("");
</script>

<CommandDialog 
  bind:open 
  bind:value 
  title="Quick Actions" 
  description="Search for commands..."
>
  <!-- Your command items go here -->
  <div class="p-4">Command List Content</div>
</CommandDialog>

The sidebar state is managed via a context-based system. You must initialize the sidebar state using setSidebar (typically within a Sidebar.Provider component or a parent component) and can then access that state in any child component using the useSidebar hook.

Important: useSidebar returns a SidebarState class instance. You cannot destructure this instance; you must access its properties directly from the returned object to maintain reactivity.

SidebarState Properties

• open: A derived boolean indicating if the sidebar is expanded.
• openMobile: A stateful boolean indicating if the sidebar is open on mobile devices.
• isMobile: A boolean indicating if the current device is detected as mobile.
• state: A derived string that is either "expanded" or "collapsed".
• toggle(): A method to switch the sidebar state. It automatically handles the distinction between mobile (openMobile) and desktop (open) states.
• setOpenMobile(value: boolean): Manually sets the mobile-specific open state.
• handleShortcutKeydown: An event handler for KeyboardEvent that can be attached to <svelte:window> to support keyboard shortcuts (using SIDEBAR_KEYBOARD_SHORTCUT with metaKey or ctrlKey).

import { setSidebar, useSidebar } from "./path-to-context";

// 1. In a parent component, initialize the state
// Note: props.open must be a getter to support two-way binding
let isOpen = $state(true);
setSidebar({
  open: () => isOpen,
  setOpen: (val) => { isOpen = val; }
});

// 2. In a child component, consume the state
const sidebar = useSidebar();

// Access properties directly (do not destructure)
console.log(sidebar.open);
console.log(sidebar.isMobile);

// Use methods
sidebar.toggle();