drab 2.8.1 → 2.8.3

package/README.md

@@ -1,7 +1,67 @@
-# drab
+# An unstyled Svelte component library
 
-## An unstyled Svelte component library
+- [GitHub](https://github.com/rossrobino/drab)
+- [npm](https://www.npmjs.com/package/drab)
+- [MIT License](https://github.com/rossrobino/drab/blob/main/LICENSE.md)
+- One dependency - [Svelte](https://svelte.dev)
 
-[drab.robino.dev](https://drab.robino.dev)
+## About
 
-### MIT License
+**drab** focuses on providing JavaScript functionality where it's most useful, while leaving out components that can be easily created using HTML, such as a label or badge. Whenever possible, components are [progressively enhanced](/docs/ShareButton) or provide a fallback [noscript](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/noscript) message. Additionally, transitions are disabled for users who prefer reduced motion.
+
+This library takes a more opinionated approach compared to some headless UI libraries by providing the basic HTML structure for every component, as well as default positioning for elements like the [sheet](/docs/Sheet) or [popover](/docs/Popover). However, these components can still be further customized using styles, [slots](https://svelte.dev/tutorial/slots), and [slot props](https://svelte.dev/tutorial/slot-props).
+
+Components without styles can appear rather drab. You have the freedom to bring your own styles to these components! Using unstyled components allows you to selectively choose what you need, seamlessly integrate with existing designs, and avoid being tied to any specific library.
+
+To style the components, you can make use of [global styles](https://joyofcode.xyz/global-styles-in-sveltekit). This process can be expedited by utilizing CSS frameworks like [TailwindCSS](https://tailwindcss.com/). TailwindCSS generates a global stylesheet based on the utility classes used in your project. Each component exports `class` and `id` props that can be leveraged for this purpose.
+
+## Install
+
+If you haven't used Svelte before, start with the [tutorial](https://svelte.dev/tutorial/basics).
+
+- [SvelteKit](https://kit.svelte.dev)
+- [Astro](https://docs.astro.build/en/tutorial/1-setup/2/)
+- [Vite](https://vitejs.dev/guide/)
+
+```bash
+npm install -D drab
+```
+
+## Documentation
+
+The library provides inline documentation for each component, allowing you to conveniently access the documentation by hovering over the component in your text editor after importing it. Additionally, every prop is documented using JSDoc and TypeScript. By hovering over a prop, you can retrieve its type and description.
+
+These docs use the [TailwindCSS Typography plugin](https://tailwindcss.com/docs/typography-plugin) for base styles along with a few custom utility classes you can find [here](https://github.com/rossrobino/drab/blob/main/src/app.postcss). Styles on this site are based on [shadcn/ui](https://ui.shadcn.com/).
+
+## Alternatives
+
+If **drab** isn't what you are looking for, here are some other Svelte UI libraries to check out.
+
+- [Skeleton](https://skeleton.dev)
+- [Melt UI](https://www.melt-ui.com/)
+- [shadcn-svelte](https://www.shadcn-svelte.com/)
+- [Svelte-HeadlessUI](https://captaincodeman.github.io/svelte-headlessui/)
+
+## Contributing
+
+Find an bug or have an idea? Feel free to create an issue on [GitHub](https://github.com/rossrobino/drab).
+
+Since this is an unstyled library, simple components like a badge that can be easily created with HTML and CSS are not included.
+
+### Local Development
+
+Contribute to the project, or use **drab** as a template for another component library. This library is built with SvelteKit, TypeScript, and npm. The package contents are located in `src/lib`, the site is contained within `src/routes` and `src/site`. The site is deployed to Vercel using `@sveltejs/adapter-vercel`. If you are using this project as a template, be sure to [update the adapter](https://kit.svelte.dev/docs/adapters) based on how you deploy.
+
+#### Make changes
+
+1. Clone the [repository](https://github.com/rossrobino/drab)
+2. `npm install`
+3. `npm run dev -- --open`
+
+#### Add or edit a component
+
+1. Add/edit the component in `src/lib/components/Component.svelte`, if you're adding a new one, copy and paste an existing one to get started with the conventions
+2. Add/edit the example in `src/routes/docs/Component/+page.svelte`
+3. Document the component with an `@component` comment, include a description, and the `@slots` available. Add a placeholder `@props` and `@example` to the comment. These sections will be generated based on the JSDoc comment above each prop and the example route created upon running `npm run doc`
+4. If new, add the link to `src/site/components/NavItems.svelte`
+5. Run `npm run build` to verify your build

package/dist/components/Accordion.svelte

@@ -3,20 +3,19 @@
 
 ### Accordion
 
-Displays a list of `details` elements with helpful defaults and transitions. Use `AccordionItem.data` to send any additional data through the slot props. Works without JavaScript. 
+Displays a list of `details` elements with helpful defaults and transitions. 
 
 @props
 
 - `autoClose` - if `true`, other items close when a new one is opened
 - `classContent` - class of all the `div`s that wrap the `content` slot
 - `classDetails` - class of the `div` around each `details` element
-- `classHeader` - class of all the `summary` elements
-- `classIcon` - class of the `div` that wrap the icon if displayed
-- `classSummary` - class of all the `div`s that wrap the `summary` slot
+- `classIcon` - class of the `div` that wraps the icon if displayed
+- `classSummary` - class of all the `summary` elements
 - `class` 
+- `data` - data to display in the accordion
 - `icon` 
 - `id` 
-- `items` - array of `AccordionItem` elements
 - `transition` - rotates the icon, slides the content, set to `false` to remove
 
 @slots
@@ -31,18 +30,10 @@ Displays a list of `details` elements with helpful defaults and transitions. Use
 
 ```svelte
 <script lang="ts">
-	import { Accordion } from "drab";
-	import { FullscreenButton } from "drab";
-	import { Chevron } from "../../site/svg/Chevron.svelte";
-</script>
+	import { Accordion, type AccordionItem, FullscreenButton } from "drab";
+	import Chevron from "../../site/svg/Chevron.svelte";
 
-<Accordion
-	icon={Chevron}
-	class="mb-12"
-	classDetails="border-b"
-	classHeader="flex gap-8 cursor-pointer items-center justify-between p-4 font-bold underline hover:decoration-dotted"
-	classContent="pb-4 px-4"
-	items={[
+	const data: AccordionItem[] = [
 		{ summary: "Is it accessible?", content: "Yes." },
 		{
 			summary: "Is it styled?",
@@ -52,35 +43,42 @@ Displays a list of `details` elements with helpful defaults and transitions. Use
 			summary: "Is it animated?",
 			content: "Yes, with the transition prop.",
 		},
+		{
+			summary: "Is it customizable?",
+			content: "Yes, customize with slots.",
+			class: "uppercase",
+			component: FullscreenButton,
+		},
 		{ summary: "Does it work without JavaScript?", content: "Yes." },
-	]}
+	];
+</script>
+
+<Accordion
+	{data}
+	icon={Chevron}
+	class="mb-12"
+	classDetails="border-b"
+	classSummary="flex gap-8 cursor-pointer items-center justify-between p-4 font-bold underline hover:decoration-dotted"
+	classContent="pb-4 px-4"
 />
 
 <Accordion
+	{data}
 	icon={Chevron}
 	classDetails="border-b"
-	classHeader="flex gap-8 cursor-pointer items-center justify-between p-4 font-bold underline hover:decoration-dotted"
+	classSummary="flex gap-8 cursor-pointer items-center justify-between p-4 font-bold underline hover:decoration-dotted"
 	classContent="pb-4 px-4"
 	autoClose={false}
-	items={[
-		{ summary: "Summary", content: "Content" },
-		{ summary: "Summary", content: "Content", data: { uppercase: true } },
-		{
-			summary: "Summary",
-			content: "Content",
-			data: { component: FullscreenButton },
-		},
-	]}
 >
 	<svelte:fragment slot="summary" let:item let:index>
-		<span class:uppercase={item.data?.uppercase}>
+		<span class={item.class ? item.class : ""}>
+			{index + 1}.
 			{item.summary}
-			{index + 1}
 		</span>
 	</svelte:fragment>
 	<svelte:fragment slot="content" let:item>
 		<span>{item.content}</span>
-		{#if item.data?.component === FullscreenButton}
+		{#if item.component === FullscreenButton}
 			<div><svelte:component this={FullscreenButton} class="btn mt-4" /></div>
 		{/if}
 	</svelte:fragment>
@@ -97,23 +95,21 @@ import { duration } from "../util/transition";
 let className = "";
 export { className as class };
 export let id = "";
-export let items;
+export let data;
 export let icon = "";
 export let classDetails = "";
-export let classHeader = "";
 export let classSummary = "";
 export let classContent = "";
 export let classIcon = "";
 export let transition = { duration };
-const cssDuration = transition ? transition.duration : 0;
 export let autoClose = true;
 let clientJs = false;
 const toggleOpen = (i) => {
-  items[i].open = !items[i].open;
+  data[i].open = !data[i].open;
   if (autoClose) {
-    for (let j = 0; j < items.length; j++) {
+    for (let j = 0; j < data.length; j++) {
       if (j !== i)
-        items[j].open = false;
+        data[j].open = false;
     }
   }
 };
@@ -125,14 +121,14 @@ onMount(() => {
 </script>
 
 <div class={className} {id}>
-	{#each items as item, index}
+	{#each data as item, index}
 		<div class={classDetails}>
 			<details bind:open={item.open}>
 				<!-- svelte-ignore a11y-no-redundant-roles -->
 				<summary
 					role="button"
 					tabindex="0"
-					class={classHeader}
+					class={classSummary}
 					on:click|preventDefault={() => toggleOpen(index)}
 					on:keydown={(e) => {
 						if (e.key === "Enter") {
@@ -141,16 +137,14 @@ onMount(() => {
 						}
 					}}
 				>
-					<div class={classSummary}>
-						<slot name="summary" {item} {index}>{item.summary}</slot>
-					</div>
+					<slot name="summary" {item} {index}>{item.summary}</slot>
 					<slot name="icon" {item} {index}>
 						{#if icon}
 							<div
 								class={classIcon}
 								class:d-rotate-180={item.open}
 								class:d-transition={transition}
-								style="--duration: {cssDuration}ms;"
+								style="--duration: {transition ? transition.duration : 0}ms;"
 							>
 								{#if typeof icon !== "string"}
 									<svelte:component this={icon} />

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

@@ -1,5 +1,5 @@
 import { SvelteComponent } from "svelte";
-export interface AccordionItem<T = any> {
+export type AccordionItem = {
     /** text summary of the item */
     summary?: string;
     /** text content of the item */
@@ -7,21 +7,20 @@ export interface AccordionItem<T = any> {
     /** controls whether the content is displayed */
     open?: boolean;
     /** any data to pass back to the parent */
-    data?: T;
-}
+    [key: string | number]: any;
+};
 import { type ComponentType } from "svelte";
 import { type SlideParams } from "svelte/transition";
 declare const __propDef: {
     props: {
         class?: string | undefined;
         id?: string | undefined;
-        /** array of `AccordionItem` elements */ items: AccordionItem[];
+        /** data to display in the accordion */ data: AccordionItem[];
         icon?: string | ComponentType | undefined;
         /** class of the `div` around each `details` element */ classDetails?: string | undefined;
-        /** class of all the `summary` elements */ classHeader?: string | undefined;
-        /** class of all the `div`s that wrap the `summary` slot */ classSummary?: string | undefined;
+        /** class of all the `summary` elements */ classSummary?: string | undefined;
         /** class of all the `div`s that wrap the `content` slot */ classContent?: string | undefined;
-        /** class of the `div` that wrap the icon if displayed */ classIcon?: string | undefined;
+        /** class of the `div` that wraps the icon if displayed */ classIcon?: string | undefined;
         /** rotates the icon, slides the content, set to `false` to remove */ transition?: false | SlideParams | undefined;
         /** if `true`, other items close when a new one is opened */ autoClose?: boolean | undefined;
     };
@@ -30,15 +29,15 @@ declare const __propDef: {
     };
     slots: {
         summary: {
-            item: AccordionItem<any>;
+            item: AccordionItem;
             index: any;
         };
         icon: {
-            item: AccordionItem<any>;
+            item: AccordionItem;
             index: any;
         };
         content: {
-            item: AccordionItem<any>;
+            item: AccordionItem;
             index: any;
         };
     };
@@ -49,20 +48,19 @@ export type AccordionSlots = typeof __propDef.slots;
 /**
  * ### Accordion
  *
- * Displays a list of `details` elements with helpful defaults and transitions. Use `AccordionItem.data` to send any additional data through the slot props. Works without JavaScript.
+ * Displays a list of `details` elements with helpful defaults and transitions.
  *
  * @props
  *
  * - `autoClose` - if `true`, other items close when a new one is opened
  * - `classContent` - class of all the `div`s that wrap the `content` slot
  * - `classDetails` - class of the `div` around each `details` element
- * - `classHeader` - class of all the `summary` elements
- * - `classIcon` - class of the `div` that wrap the icon if displayed
- * - `classSummary` - class of all the `div`s that wrap the `summary` slot
+ * - `classIcon` - class of the `div` that wraps the icon if displayed
+ * - `classSummary` - class of all the `summary` elements
  * - `class`
+ * - `data` - data to display in the accordion
  * - `icon`
  * - `id`
- * - `items` - array of `AccordionItem` elements
  * - `transition` - rotates the icon, slides the content, set to `false` to remove
  *
  * @slots
@@ -77,18 +75,10 @@ export type AccordionSlots = typeof __propDef.slots;
  *
  * ```svelte
  * <script lang="ts">
- * import { Accordion } from "drab";
- * import { FullscreenButton } from "drab";
- * import { Chevron } from "../../site/svg/Chevron.svelte";
- * </script>
+ * import { Accordion, type AccordionItem, FullscreenButton } from "drab";
+ * import Chevron from "../../site/svg/Chevron.svelte";
  *
- * <Accordion
- * icon={Chevron}
- * class="mb-12"
- * classDetails="border-b"
- * classHeader="flex gap-8 cursor-pointer items-center justify-between p-4 font-bold underline hover:decoration-dotted"
- * classContent="pb-4 px-4"
- * items={[
+ * const data: AccordionItem[] = [
  * 	{ summary: "Is it accessible?", content: "Yes." },
  * 	{
  * 		summary: "Is it styled?",
@@ -98,35 +88,42 @@ export type AccordionSlots = typeof __propDef.slots;
  * 		summary: "Is it animated?",
  * 		content: "Yes, with the transition prop.",
  * 	},
+ * 	{
+ * 		summary: "Is it customizable?",
+ * 		content: "Yes, customize with slots.",
+ * 		class: "uppercase",
+ * 		component: FullscreenButton,
+ * 	},
  * 	{ summary: "Does it work without JavaScript?", content: "Yes." },
- * ]}
+ * ];
+ * </script>
+ *
+ * <Accordion
+ * {data}
+ * icon={Chevron}
+ * class="mb-12"
+ * classDetails="border-b"
+ * classSummary="flex gap-8 cursor-pointer items-center justify-between p-4 font-bold underline hover:decoration-dotted"
+ * classContent="pb-4 px-4"
  * />
  *
  * <Accordion
+ * {data}
  * icon={Chevron}
  * classDetails="border-b"
- * classHeader="flex gap-8 cursor-pointer items-center justify-between p-4 font-bold underline hover:decoration-dotted"
+ * classSummary="flex gap-8 cursor-pointer items-center justify-between p-4 font-bold underline hover:decoration-dotted"
  * classContent="pb-4 px-4"
  * autoClose={false}
- * items={[
- * 	{ summary: "Summary", content: "Content" },
- * 	{ summary: "Summary", content: "Content", data: { uppercase: true } },
- * 	{
- * 		summary: "Summary",
- * 		content: "Content",
- * 		data: { component: FullscreenButton },
- * 	},
- * ]}
  * >
  * <svelte:fragment slot="summary" let:item let:index>
- * 	<span class:uppercase={item.data?.uppercase}>
+ * 	<span class={item.class ? item.class : ""}>
+ * 		{index + 1}.
  * 		{item.summary}
- * 		{index + 1}
  * 	</span>
  * </svelte:fragment>
  * <svelte:fragment slot="content" let:item>
  * 	<span>{item.content}</span>
- * 	{#if item.data?.component === FullscreenButton}
+ * 	{#if item.component === FullscreenButton}
  * 		<div><svelte:component this={FullscreenButton} class="btn mt-4" /></div>
  * 	{/if}
  * </svelte:fragment>

package/dist/components/ContextMenu.svelte

@@ -11,7 +11,7 @@ Displays when the `target` element is right clicked, or long pressed on mobile.
 - `display` - shows / hides the menu
 - `id` 
 - `target` - target element to right click, defaults to the parent element
-- `transition` - fades the content, set to `false` to remove
+- `transition` - scales the menu, set to `false` to disable
 
 @slots
 
@@ -40,7 +40,7 @@ Displays when the `target` element is right clicked, or long pressed on mobile.
 	</ContextMenu>
 </div>
 
-<button class="btn" bind:this={target}>Target Right Click</button>
+<button type="button" class="btn" bind:this={target}>Target Right Click</button>
 <ContextMenu {target}>
 	<div class="flex w-48 flex-col gap-2 rounded border bg-white p-2 shadow">
 		<div class="font-bold">Context Menu</div>
@@ -53,15 +53,15 @@ Displays when the `target` element is right clicked, or long pressed on mobile.
 -->
 
 <script>import { onMount, tick } from "svelte";
-import { fade } from "svelte/transition";
-import { duration } from "../util/transition";
+import { scale } from "svelte/transition";
+import { duration, start } from "../util/transition";
 import { prefersReducedMotion } from "../util/accessibility";
 import { delay } from "../util/delay";
 let className = "";
 export { className as class };
 export let id = "";
 export let display = false;
-export let transition = { duration };
+export let transition = { duration, start };
 export let target = null;
 let contextMenu;
 let base;
@@ -102,11 +102,10 @@ const onTouchStart = (e) => {
 const onTouchEnd = () => {
   clearTimeout(timer);
 };
-onMount(() => {
-  if (prefersReducedMotion()) {
-    if (transition)
-      transition.duration = 0;
-  }
+onMount(async () => {
+  if (prefersReducedMotion())
+    transition = false;
+  await tick();
   if (!target) {
     target = base.parentElement;
   }
@@ -131,7 +130,7 @@ onMount(() => {
 		bind:this={contextMenu}
 		style:top="{coordinates.y}px"
 		style:left="{coordinates.x}px"
-		transition:fade={transition ? transition : { duration: 0 }}
+		transition:scale={transition ? transition : { duration: 0 }}
 	>
 		<slot>Context Menu</slot>
 	</div>

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

@@ -1,11 +1,11 @@
 import { SvelteComponent } from "svelte";
-import { type FadeParams } from "svelte/transition";
+import { type ScaleParams } from "svelte/transition";
 declare const __propDef: {
     props: {
         class?: string | undefined;
         id?: string | undefined;
         /** shows / hides the menu */ display?: boolean | undefined;
-        /** fades the content, set to `false` to remove */ transition?: false | FadeParams | undefined;
+        /** scales the menu, set to `false` to disable */ transition?: false | ScaleParams | undefined;
         /** target element to right click, defaults to the parent element */ target?: HTMLElement | null | undefined;
     };
     events: {
@@ -29,7 +29,7 @@ export type ContextMenuSlots = typeof __propDef.slots;
  * - `display` - shows / hides the menu
  * - `id`
  * - `target` - target element to right click, defaults to the parent element
- * - `transition` - fades the content, set to `false` to remove
+ * - `transition` - scales the menu, set to `false` to disable
  *
  * @slots
  *
@@ -58,7 +58,7 @@ export type ContextMenuSlots = typeof __propDef.slots;
  * </ContextMenu>
  * </div>
  *
- * <button class="btn" bind:this={target}>Target Right Click</button>
+ * <button type="button" class="btn" bind:this={target}>Target Right Click</button>
  * <ContextMenu {target}>
  * <div class="flex w-48 flex-col gap-2 rounded border bg-white p-2 shadow">
  * 	<div class="font-bold">Context Menu</div>