@f0rbit/ui 0.1.2 → 0.1.7

package/src/components/Stepper.tsx

@@ -18,6 +18,11 @@ export interface StepProps extends JSX.HTMLAttributes<HTMLDivElement> {
 	description?: string;
 	icon?: JSX.Element;
 	status?: StepStatus;
+	children?: JSX.Element;
+	/** Explicit step number (optional, auto-increments if not provided) */
+	number?: number;
+	/** Explicit orientation (optional, uses context if not provided) */
+	orientation?: "horizontal" | "vertical";
 }
 
 const statusClasses: Record<StepStatus, string> = {
@@ -41,12 +46,12 @@ type StepContextValue = {
 const StepContext = createContext<StepContextValue>();
 
 export function Step(props: StepProps) {
-	const [local, rest] = splitProps(props, ["title", "description", "icon", "status", "class"]);
+	const [local, rest] = splitProps(props, ["title", "description", "icon", "status", "class", "children", "number", "orientation"]);
 	const stepperCtx = useContext(StepperContext);
 	const stepCtx = useContext(StepContext);
 
-	const stepNumber = stepperCtx?.registerStep() ?? 1;
-	const orientation = () => stepCtx?.orientation() ?? "horizontal";
+	const stepNumber = local.number ?? stepperCtx?.registerStep() ?? 1;
+	const orientation = () => local.orientation ?? stepCtx?.orientation() ?? "vertical";
 
 	const status = () => local.status ?? "upcoming";
 
@@ -105,6 +110,9 @@ export function Step(props: StepProps) {
 				<Show when={local.description}>
 					<div class="step-description">{local.description}</div>
 				</Show>
+				<Show when={local.children}>
+					<div class="step-body">{local.children}</div>
+				</Show>
 			</div>
 			<div class={connectorClasses()} />
 		</div>

package/src/components/Tabs.tsx

@@ -1,62 +1,146 @@
-import { type JSX, splitProps, createSignal, createContext, useContext, Show, For } from "solid-js";
-
-type TabsContextValue = {
-	activeTab: () => string;
-	setActiveTab: (id: string) => void;
-};
-
-const TabsContext = createContext<TabsContextValue>();
-
+import { type JSX, splitProps, onMount, onCleanup, createSignal } from "solid-js";
+
+/**
+ * A tab container component that manages tab selection and panel visibility.
+ *
+ * Uses DOM-based discovery via data attributes, making it compatible with
+ * Astro's island architecture where each child component hydrates independently.
+ *
+ * @example Basic usage in SolidJS
+ * ```tsx
+ * <Tabs defaultValue="tab1">
+ *   <TabList>
+ *     <Tab value="tab1">First Tab</Tab>
+ *     <Tab value="tab2">Second Tab</Tab>
+ *   </TabList>
+ *   <TabPanel value="tab1">First panel content</TabPanel>
+ *   <TabPanel value="tab2">Second panel content</TabPanel>
+ * </Tabs>
+ * ```
+ *
+ * @example Usage in Astro MDX (each component needs client:load)
+ * ```mdx
+ * <Tabs defaultValue="tab1" client:load>
+ *   <TabList client:load>
+ *     <Tab value="tab1" client:load>First Tab</Tab>
+ *     <Tab value="tab2" client:load>Second Tab</Tab>
+ *   </TabList>
+ *   <TabPanel value="tab1" client:load>First panel content</TabPanel>
+ *   <TabPanel value="tab2" client:load>Second panel content</TabPanel>
+ * </Tabs>
+ * ```
+ *
+ * @example Creating a wrapper to avoid multiple client:load directives
+ * ```tsx
+ * // MyTabs.tsx - your custom wrapper
+ * import { Tabs, TabList, Tab, TabPanel } from '@f0rbit/ui';
+ *
+ * export function MyTabs() {
+ *   return (
+ *     <Tabs defaultValue="tab1">
+ *       <TabList>
+ *         <Tab value="tab1">First</Tab>
+ *         <Tab value="tab2">Second</Tab>
+ *       </TabList>
+ *       <TabPanel value="tab1">Content 1</TabPanel>
+ *       <TabPanel value="tab2">Content 2</TabPanel>
+ *     </Tabs>
+ *   );
+ * }
+ *
+ * // Then in Astro: <MyTabs client:load />
+ * ```
+ */
 export interface TabsProps extends JSX.HTMLAttributes<HTMLDivElement> {
+	/** The value of the initially selected tab */
 	defaultValue?: string;
-	value?: string;
-	onValueChange?: (value: string) => void;
 	children: JSX.Element;
 }
 
-export interface TabListProps extends JSX.HTMLAttributes<HTMLDivElement> {
-	children: JSX.Element;
-}
+export function Tabs(props: TabsProps) {
+	const [local, rest] = splitProps(props, ["defaultValue", "children", "class"]);
+	let containerRef: HTMLDivElement | undefined;
+	const [activeTab, setActiveTab] = createSignal(local.defaultValue ?? "");
+
+	const updateTabs = (value: string) => {
+		if (!containerRef) return;
+
+		const tabs = containerRef.querySelectorAll<HTMLButtonElement>("[data-tab-value]");
+		tabs.forEach((tab) => {
+			const isActive = tab.dataset.tabValue === value;
+			tab.setAttribute("aria-selected", String(isActive));
+			tab.setAttribute("tabindex", isActive ? "0" : "-1");
+			tab.classList.toggle("active", isActive);
+		});
+
+		const panels = containerRef.querySelectorAll<HTMLDivElement>("[data-panel-value]");
+		panels.forEach((panel) => {
+			const isActive = panel.dataset.panelValue === value;
+			panel.hidden = !isActive;
+		});
+	};
 
-export interface TabProps extends JSX.ButtonHTMLAttributes<HTMLButtonElement> {
-	value: string;
-	children: JSX.Element;
-}
+	const initializeTabs = () => {
+		if (!containerRef) return;
 
-export interface TabPanelProps extends JSX.HTMLAttributes<HTMLDivElement> {
-	value: string;
-	children: JSX.Element;
-}
+		let value = activeTab();
+		if (!value) {
+			const firstTab = containerRef.querySelector<HTMLButtonElement>("[data-tab-value]");
+			value = firstTab?.dataset.tabValue ?? "";
+			if (value) setActiveTab(value);
+		}
 
-export function Tabs(props: TabsProps) {
-	const [local, rest] = splitProps(props, ["defaultValue", "value", "onValueChange", "children", "class"]);
+		if (value) updateTabs(value);
+	};
 
-	const [internalValue, setInternalValue] = createSignal(local.defaultValue ?? "");
+	onMount(() => {
+		if (!containerRef) return;
 
-	const isControlled = () => local.value !== undefined;
-	const activeTab = () => (isControlled() ? local.value! : internalValue());
+		// Use event delegation for clicks - handles dynamically added children
+		containerRef.addEventListener("click", (e) => {
+			const tab = (e.target as HTMLElement).closest<HTMLButtonElement>("[data-tab-value]");
+			if (tab?.dataset.tabValue) {
+				setActiveTab(tab.dataset.tabValue);
+				updateTabs(tab.dataset.tabValue);
+			}
+		});
 
-	const setActiveTab = (id: string) => {
-		if (!isControlled()) {
-			setInternalValue(id);
-		}
-		local.onValueChange?.(id);
-	};
+		// Initialize with any children already present
+		initializeTabs();
+
+		// Watch for new children being added (e.g., Astro islands hydrating)
+		const observer = new MutationObserver(() => {
+			initializeTabs();
+		});
+
+		observer.observe(containerRef, {
+			childList: true,
+			subtree: true,
+		});
+
+		onCleanup(() => observer.disconnect());
+	});
 
 	const classes = () => `tabs ${local.class ?? ""}`.trim();
 
 	return (
-		<TabsContext.Provider value={{ activeTab, setActiveTab }}>
-			<div class={classes()} {...rest}>
-				{local.children}
-			</div>
-		</TabsContext.Provider>
+		<div ref={containerRef} class={classes()} data-default-value={local.defaultValue} {...rest}>
+			{local.children}
+		</div>
 	);
 }
 
+/**
+ * Container for Tab buttons. Provides the tablist role for accessibility.
+ *
+ * In Astro, requires `client:load` directive.
+ */
+export interface TabListProps extends JSX.HTMLAttributes<HTMLDivElement> {
+	children: JSX.Element;
+}
+
 export function TabList(props: TabListProps) {
 	const [local, rest] = splitProps(props, ["children", "class"]);
-
 	const classes = () => `tab-list ${local.class ?? ""}`.trim();
 
 	return (
@@ -66,35 +150,30 @@ export function TabList(props: TabListProps) {
 	);
 }
 
+/**
+ * A tab button that switches the active panel when clicked.
+ *
+ * The `value` prop must match a corresponding `TabPanel` value.
+ * In Astro, requires `client:load` directive.
+ */
+export interface TabProps extends JSX.ButtonHTMLAttributes<HTMLButtonElement> {
+	/** Unique identifier that links this tab to its panel */
+	value: string;
+	children: JSX.Element;
+}
+
 export function Tab(props: TabProps) {
 	const [local, rest] = splitProps(props, ["value", "children", "class"]);
-	const ctx = useContext(TabsContext);
-
-	const isActive = () => ctx?.activeTab() === local.value;
-
-	const handleClick = () => {
-		ctx?.setActiveTab(local.value);
-	};
-
-	const classes = () => {
-		const parts = ["tab"];
-		if (isActive()) {
-			parts.push("active");
-		}
-		if (local.class) {
-			parts.push(local.class);
-		}
-		return parts.join(" ");
-	};
+	const classes = () => `tab ${local.class ?? ""}`.trim();
 
 	return (
 		<button
 			type="button"
 			role="tab"
-			aria-selected={isActive()}
-			tabIndex={isActive() ? 0 : -1}
+			aria-selected="false"
+			tabIndex={-1}
 			class={classes()}
-			onClick={handleClick}
+			data-tab-value={local.value}
 			{...rest}
 		>
 			{local.children}
@@ -102,19 +181,26 @@ export function Tab(props: TabProps) {
 	);
 }
 
+/**
+ * Content panel that is shown when its corresponding Tab is active.
+ *
+ * The `value` prop must match a corresponding `Tab` value.
+ * Panels are hidden by default and shown when their tab is selected.
+ * In Astro, requires `client:load` directive.
+ */
+export interface TabPanelProps extends JSX.HTMLAttributes<HTMLDivElement> {
+	/** Unique identifier that links this panel to its tab */
+	value: string;
+	children: JSX.Element;
+}
+
 export function TabPanel(props: TabPanelProps) {
 	const [local, rest] = splitProps(props, ["value", "children", "class"]);
-	const ctx = useContext(TabsContext);
-
-	const isActive = () => ctx?.activeTab() === local.value;
-
 	const classes = () => `tab-panel ${local.class ?? ""}`.trim();
 
 	return (
-		<Show when={isActive()}>
-			<div class={classes()} role="tabpanel" {...rest}>
-				{local.children}
-			</div>
-		</Show>
+		<div class={classes()} role="tabpanel" data-panel-value={local.value} hidden {...rest}>
+			{local.children}
+		</div>
 	);
 }

package/src/styles/components.css

@@ -700,6 +700,10 @@
 		color: var(--fg-muted);
 	}
 
+	.step-body {
+		margin-top: var(--space-sm);
+	}
+
 	/* Tabs */
 	.tabs {
 		display: flex;

package/src/styles/starlight.css

@@ -0,0 +1,243 @@
+/* Starlight Theme Overrides */
+
+/* Map library tokens to Starlight variables */
+:root {
+	--code-background: oklch(from var(--bg) calc(l - 0.03) c h);
+	--ec-codeBg: var(--code-background);
+	--sl-color-bg: var(--bg);
+	--sl-color-bg-nav: var(--bg);
+	--sl-color-bg-sidebar: var(--bg);
+	--sl-color-text: var(--fg-muted);
+	--sl-color-text-accent: var(--accent);
+	--sl-color-hairline: var(--border);
+	--sl-color-hairline-light: var(--border);
+	--sl-font: var(--font);
+	--sl-font-system: var(--font);
+	--sl-font-mono: var(--font-mono);
+	--sl-color-accent-low: var(--bg);
+	--sl-color-accent: var(--accent);
+	--sl-color-accent-high: var(--fg);
+	--sl-color-white: var(--fg);
+	--sl-color-gray-1: var(--fg-muted);
+	--sl-color-gray-2: var(--fg-subtle);
+	--sl-color-gray-3: var(--fg-faint);
+	--sl-color-gray-4: var(--border);
+	--sl-color-gray-5: var(--bg-alt);
+	--sl-color-gray-6: var(--bg);
+	--sl-color-black: var(--bg);
+}
+
+/* Header - smaller height and border */
+:root {
+	--sl-nav-height: 2.75rem;
+}
+
+@media (min-width: 50rem) {
+	:root {
+		--sl-nav-height: 3rem;
+	}
+}
+
+header.header {
+	border-bottom: 1px solid var(--border);
+}
+
+/* Apply stack spacing to markdown content */
+.sl-markdown-content {
+	display: flex;
+	flex-direction: column;
+	gap: var(--space-md);
+}
+
+/* Override Starlight's aggressive content margin rules */
+.sl-markdown-content :not(h1, h2, h3, h4, h5, h6) + :is(h1, h2, h3, h4, h5, h6):not(:where(.not-content, .sl-steps *)) {
+	margin-top: 0 !important;
+}
+.sl-markdown-content :not(a, strong, em, del, span, input, code, br) + :not(a, strong, em, del, span, input, code, br, :where(.not-content, .sl-steps *)) {
+	margin-top: 0 !important;
+}
+
+/* Hide Starlight's default splash hero/tagline/banner/title on landing page */
+.sl-hero,
+.tagline,
+.sl-banner {
+	display: none;
+}
+
+/* Hide the content panel containing the splash page title placeholder */
+.content-panel:has(.splash-title-placeholder) {
+	display: none;
+}
+
+.splash-title-placeholder {
+	display: none;
+}
+
+/* Hide the empty content panel with just an h1#_top on splash pages */
+.content-panel:has(> .sl-container > h1#_top:only-child:empty) {
+	display: none;
+}
+
+/* Sidebar border */
+nav .sidebar-pane {
+	border-right: 1px solid var(--border);
+}
+
+/* Remove content max-width constraint */
+.main-pane .sl-container {
+	max-width: unset;
+}
+
+main {
+	padding-bottom: unset !important;
+}
+
+/* Cap "On this page" TOC width and adjust main pane on large screens */
+@media (min-width: 72rem) {
+	.right-sidebar-panel .sl-container {
+		max-width: 25rem;
+		width: 25rem;
+	}
+
+	[data-has-sidebar][data-has-toc] .main-pane {
+		width: 100%;
+	}
+
+	.right-sidebar-container {
+		width: 25rem;
+	}
+}
+
+/* Selected sidebar item - override Starlight defaults */
+[aria-current="page"],
+[aria-current="page"]:hover,
+[aria-current="page"]:focus {
+	background-color: transparent;
+	color: var(--fg);
+	text-decoration: underline;
+	font-weight: 500;
+}
+
+/* Reduce title sizes */
+h1#_top,
+.content-panel h1 {
+	font-size: 1.5rem;
+}
+
+.sl-markdown-content h1 {
+	font-size: 1.5rem;
+}
+
+.sl-markdown-content h2 {
+	font-size: 1.25rem;
+}
+
+.sl-markdown-content h3 {
+	font-size: 1.125rem;
+}
+
+.sl-markdown-content h4,
+.sl-markdown-content h5,
+.sl-markdown-content h6 {
+	font-size: 1rem;
+}
+
+/* Apply library .list styles to markdown content lists */
+.sl-markdown-content ul,
+.sl-markdown-content ol {
+	padding-left: var(--space-lg);
+}
+
+.sl-markdown-content ul {
+	list-style-type: disc;
+}
+
+.sl-markdown-content ol {
+	list-style-type: decimal;
+}
+
+.sl-markdown-content li {
+	position: relative;
+	padding-left: var(--space-sm);
+	margin-bottom: var(--space-xs);
+}
+
+.sl-markdown-content li::marker {
+	color: var(--fg-faint);
+}
+
+.sl-markdown-content li:last-child {
+	margin-bottom: 0;
+}
+
+.sl-markdown-content :is(ul, ol) :is(ul, ol) {
+	margin-top: var(--space-xs);
+}
+
+.sl-markdown-content ul ul {
+	list-style-type: circle;
+}
+
+.sl-markdown-content ul ul ul {
+	list-style-type: square;
+}
+
+.sl-markdown-content ol ol {
+	list-style-type: lower-alpha;
+}
+
+.sl-markdown-content ol ol ol {
+	list-style-type: lower-roman;
+}
+
+/* Override expressive-code backgrounds */
+.expressive-code,
+.expressive-code pre,
+.expressive-code code,
+.expressive-code .frame {
+	background: var(--code-background);
+}
+
+/* Pagination - compact button style */
+.pagination-links {
+	gap: var(--space-sm);
+}
+
+.pagination-links a {
+	padding: var(--space-sm) var(--space-md);
+	border: 1px solid var(--border);
+	border-radius: var(--radius);
+	box-shadow: none;
+	color: var(--fg-muted);
+	background: transparent;
+	transition: border-color var(--transition), color var(--transition);
+}
+
+.pagination-links a:hover {
+	border-color: var(--fg-faint);
+	color: var(--fg);
+}
+
+/* Hide "Previous"/"Next" text, keep only the page title */
+.pagination-links a > span {
+	font-size: 0;
+	line-height: 0;
+	height: 1.35rem;
+}
+
+.pagination-links a > span br {
+	display: none;
+}
+
+.pagination-links .link-title {
+	font-size: var(--text-sm);
+	color: var(--fg);
+	font-weight: 500;
+	line-height: var(--sl-line-height);
+}
+
+.pagination-links svg {
+	width: 1rem;
+	height: 1rem;
+	color: var(--fg-faint);
+}