next: Docs work (#605)

huntabyte · Jul 10, 2024 · d59f4a5 · d59f4a5
1 parent aed0474
commit d59f4a5
Show file tree

Hide file tree

Showing 17 changed files with 459 additions and 266 deletions.
diff --git a/NOTES.md b/NOTES.md
@@ -26,3 +26,7 @@ We need to determine the ideal approach for managing the `data-<component>` attr
 Since other components depend on these attributes for selectors, we'll need to put them in a place where they can be easily accessed and if changed, those changes will propagate to everywhere the attribute is used.
 
 They also need to be flexible enough to allow for reusing the same component while swapping the `data-component` prefix, for example, in the menus we have `data-menubar-*`, `data-dropdown-menu-*`, `data-context-menu-*`, etc. The easy button is of course to just consolidate these into just a single `data-menu` attribute, but that's not ideal and hinders the ability to apply different styles on a global level to the different components.
+
+---
+
+Should we embrace the [ValidityState](https://developer.mozilla.org/en-US/docs/Web/API/ValidityState) API? Something to think about.
diff --git a/packages/bits-ui/src/lib/bits/alert-dialog/ctx.ts b/packages/bits-ui/src/lib/bits/alert-dialog/ctx.ts
diff --git a/sites/docs/content/components/accordion.md b/sites/docs/content/components/accordion.md
@@ -31,41 +31,161 @@ description: Organizes content into collapsible sections, allowing users to focu
 </Accordion.Root>
 ```
 
-<APISection {schemas} />
+## Usage
+
+### Single
 
-## Examples
+Set the `type` prop to `"single"` to allow only one accordion item to be open at a time.
+
+```svelte {1}
+<Accordion.Root type="single">
+	<!-- ... -->
+</Accordion.Root>
+```
 
 ### Multiple
 
-Multiple accordion items open at the same time using the `multiple` prop.
+Set the `type` prop to `"multiple"` to allow multiple accordion items to be open at the same time.
 
-```svelte showLineNumbers {1}
-<Accordion.Root multiple>
+```svelte {1}
+<Accordion.Root type="multiple">
 	<!-- ... -->
 </Accordion.Root>
 ```
 
-### Controlled
+### Disable Items
+
+To disable an individual accordion item, set the `disabled` prop to `true`. This will prevent users from interacting with the item.
+
+```svelte {2}
+<Accordion.Root type="single">
+	<Accordion.Item value="item-1" disabled>
+		<!-- ... -->
+	</Accordion.Item>
+</Accordion.Root>
+```
+
+### Controlled Value
 
 You can programmatically control the active of the accordion item(s) using the `value` prop.
 
-```svelte showLineNumbers
+```svelte
 <script lang="ts">
-	let value = "item-1";
+	let value = $state("item-1");
 </script>
 
+<button onclick={() => (value = "item-2")}>Change value</button>
+
 <Accordion.Root bind:value>
-	<Accordion.Item value="item-1">
-		<Accordion.Header>
-			<Accordion.Trigger />
-		</Accordion.Header>
-		<Accordion.Content />
-	</Accordion.Item>
-	<Accordion.Item value="item-2">
-		<Accordion.Header>
-			<Accordion.Trigger />
-		</Accordion.Header>
-		<Accordion.Content />
-	</Accordion.Item>
+	<!-- ... -->
+</Accordion.Root>
+```
+
+### Value Change Side Effects
+
+You can use the `onValueChange` prop to handle side effects when the value of the accordion changes.
+
+```svelte
+<Accordion.Root
+	onValueChange={(value) => {
+		doSomething(value);
+	}}
+>
+	<!-- ... -->
 </Accordion.Root>
 ```
+
+Alternatively, you can use `bind:value` with an `$effect` block to handle side effects when the value of the accordion changes.
+
+```svelte
+<script lang="ts">
+	import { Accordion } from "bits-ui";
+
+	let value = $state("item-1")
+
+	$effect(() => {
+		doSomething(value);
+	})
+</script>
+
+<Accordion.Root bind:value>
+	<!-- ... -->
+</Accordion.Item>
+```
+
+## Reusable Wrappers
+
+### Entire Component
+
+If you're going to be using the same accordion component multiple places throughout your app, you can create a reusable wrapper to reduce the amount of code you need to write each time.
+
+```svelte title="CustomAccordion.svelte"
+<script lang="ts">
+	import { Accordion, type WithoutChildren } from "bits-ui";
+
+	type Props = WithoutChildren<Accordion.RootProps> & {
+		items: Array<{
+			value: string;
+			disabled?: boolean;
+			title: string;
+			content: string;
+		}>;
+	};
+
+	let { items, value = $bindable(""), ...restProps }: Props = $props();
+</script>
+
+<Accordion.Root bind:value {...restProps}>
+	{#each items as item}
+		<Accordion.Item value={item.value} disabled={item.disabled}>
+			<Accordion.Header>
+				<Accordion.Trigger>{item.title}</Accordion.Trigger>
+			</Accordion.Header>
+			<Accordion.Content>{item.content}</Accordion.Content>
+		</Accordion.Item>
+	{/each}
+</Accordion.Root>
+```
+
+### Individual Item
+
+For each invidual item, you need an `Accordion.Item`, `Accordion.Header`, `Accordion.Trigger` and `Accordion.Content` component. You can make a reusable wrapper to reduce the amount of code you need to write each time.
+
+```svelte title="CustomAcccordionItem.svelte"
+<script lang="ts">
+	import { Accordion, type WithoutChildren } from "bits-ui";
+
+	type Props = WithoutChildren<Accordion.ItemProps> & {
+		title: string;
+		content: string;
+	};
+
+	let { title, content, ...restProps }: Props = $props();
+</script>
+
+<Accordion.Item {...restProps}>
+	<Accordion.Header>
+		<Accordion.Trigger>
+			{title}
+		</Accordion.Trigger>
+	</Accordion.Header>
+	<Accordion.Content>
+		{content}
+	</Accordion.Content>
+</Accordion.Item>
+```
+
+```svelte title="+page.svelte"
+<script lang="ts">
+	import { Accordion } from "bits-ui";
+	import CustomAccordionItem from "$lib/components/CustomAccordionItem.svelte";
+</script>
+
+<Accordion.Root type="single">
+	<CustomAccordionItem title="Item 1" content="Content 1" />
+	<CustomAccordionItem title="Item 2" content="Content 2" />
+	<CustomAccordionItem title="Item 3" content="Content 3" />
+</Accordion.Root>
+```
+
+<APISection {schemas} />