@zealakit/disclosure-svelte 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,262 @@
-# Temporary Holding Version
+# @zealakit/disclosure-svelte
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[English](https://github.com/zealakit/disclosure/blob/main/packages/svelte/README.md) | [Tiếng Việt](https://github.com/zealakit/disclosure/blob/main/packages/svelte/README_VI.md) | [中文](https://github.com/zealakit/disclosure/blob/main/packages/svelte/README_CN.md)
+
+![Disclosure cover](https://github.com/zealakit/disclosure/blob/main/assets/images/disclosure-cover.jpg?raw=true)
+
+Headless Collapsible and Accordion for Svelte 5. Built-in height animation is enabled by default. You own visual styling.
+
+Apply padding, borders, and backgrounds via `class` on `CollapsibleContent` / `AccordionContent` (or `[data-collapsible-content-wrapper]`). Those styles land on the clipped content panel so exit animations collapse cleanly.
+
+> **Note**
+>
+> Disclosure is not a replacement for a full UI library. Use it when Accordion or Collapsible in your kit is hard to restyle — or when you only need that one primitive and don’t want to pull in a large design system.
+
+## Install
+
+```bash
+npm i @zealakit/disclosure-svelte
+# or: pnpm add / yarn add / bun add
+```
+
+Peer dependency: `svelte` (^5).
+
+## Collapsible
+
+### Quick start
+
+```svelte
+<script lang="ts">
+  import {
+    Collapsible,
+    CollapsibleTrigger,
+    CollapsibleContent,
+  } from "@zealakit/disclosure-svelte";
+</script>
+
+<Collapsible>
+  <CollapsibleTrigger>Toggle</CollapsibleTrigger>
+  <CollapsibleContent>Content</CollapsibleContent>
+</Collapsible>
+```
+
+### `Collapsible` props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `defaultOpen` | `boolean` | `false` | Initial open state when uncontrolled |
+| `open` | `boolean` | — | Controlled open state (`bind:open`) |
+| `onOpenChange` | `(open: boolean) => void` | — | Called when open state should change |
+| `disabled` | `boolean` | `false` | Disables the whole collapsible |
+| `animated` | `boolean` | `true` | Enables height expand/collapse animation |
+| `animationTimingFunction` | `"linear" \| "ease-in-out"` | `"ease-in-out"` | Transition easing |
+| `animationDuration` | `number` | `200` | Duration in milliseconds |
+| `animationDelay` | `number` | `0` | Delay in milliseconds |
+| `class` / other attrs | — | — | Forwarded to the root element |
+
+Root attributes: `data-slot="collapsible"`, `data-state="open" | "closed"`, `data-disabled` when disabled.
+
+### `CollapsibleTrigger` props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `disabled` | `boolean` | inherits root | Disables this trigger |
+| `class` / other attrs | — | — | Forwarded to the native `<button>` |
+
+Sets `aria-expanded`, `aria-controls`, `data-slot="collapsible-trigger"`, and `data-state`.
+
+### `CollapsibleContent` props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `forceMount` | `boolean` | `false` | Keep content in the DOM while closed |
+| `class` / `style` | — | — | Applied to the **inner** content wrapper (clipped during animation) |
+| other attrs | — | — | Forwarded to the inner wrapper |
+
+Put borders/padding on the content wrapper, not only on the animated viewport.
+
+### Controlled usage
+
+```svelte
+<script lang="ts">
+  import {
+    Collapsible,
+    CollapsibleTrigger,
+    CollapsibleContent,
+  } from "@zealakit/disclosure-svelte";
+
+  let open = $state(false);
+</script>
+
+<Collapsible bind:open>
+  <CollapsibleTrigger>Toggle</CollapsibleTrigger>
+  <CollapsibleContent>Content</CollapsibleContent>
+</Collapsible>
+```
+
+### Animation configuration
+
+```svelte
+<Collapsible
+  animationTimingFunction="linear"
+  animationDuration={300}
+  animationDelay={50}
+>
+  <CollapsibleTrigger>Toggle</CollapsibleTrigger>
+  <CollapsibleContent>Content</CollapsibleContent>
+</Collapsible>
+```
+
+```svelte
+<Collapsible animated={false}>
+  <CollapsibleTrigger>Instant</CollapsibleTrigger>
+  <CollapsibleContent>No height transition</CollapsibleContent>
+</Collapsible>
+```
+
+When `animated={false}`, open/close updates immediately and duration/delay are ignored. `prefers-reduced-motion` also disables motion.
+
+CSS variables on the content viewport:
+
+- `--collapsible-animation-duration`
+- `--collapsible-animation-easing`
+- `--collapsible-animation-delay`
+
+### `forceMount`
+
+```svelte
+<CollapsibleContent forceMount>
+  Stays mounted while closed (`inert`; `hidden` when not animated).
+</CollapsibleContent>
+```
+
+## Accordion
+
+### Quick start
+
+```svelte
+<script lang="ts">
+  import {
+    Accordion,
+    AccordionItem,
+    AccordionTrigger,
+    AccordionContent,
+  } from "@zealakit/disclosure-svelte";
+</script>
+
+<Accordion type="single" collapsible>
+  <AccordionItem value="general">
+    <AccordionTrigger>General</AccordionTrigger>
+    <AccordionContent>General content</AccordionContent>
+  </AccordionItem>
+  <AccordionItem value="advanced">
+    <AccordionTrigger>Advanced</AccordionTrigger>
+    <AccordionContent>Advanced content</AccordionContent>
+  </AccordionItem>
+</Accordion>
+```
+
+### `Accordion` props (shared)
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `type` | `"single" \| "multiple"` | `"single"` | Selection mode |
+| `animated` | `boolean` | `true` | Height animation for item panels |
+| `animationTimingFunction` | `"linear" \| "ease-in-out"` | `"ease-in-out"` | Easing for all items |
+| `animationDuration` | `number` | `200` | Duration in milliseconds |
+| `animationDelay` | `number` | `0` | Delay in milliseconds |
+| `disabled` | `boolean` | `false` | Disables the whole accordion |
+| `class` / other attrs | — | — | Forwarded to the root element |
+
+Animation props are owned by the Accordion root and inherited by every item.
+
+### `Accordion` props (`type="single"`)
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value` | `string \| null` | — | Controlled open item (`bind:value`) |
+| `defaultValue` | `string \| null` | `null` | Uncontrolled initial item |
+| `collapsible` | `boolean` | `false` | Allow closing the open item |
+| `onValueChange` | `(value: string \| null) => void` | — | Value change callback |
+
+### `Accordion` props (`type="multiple"`)
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value` | `string[]` | — | Controlled open items (`bind:value`) |
+| `defaultValue` | `string[]` | `[]` | Uncontrolled initial items |
+| `onValueChange` | `(value: string[]) => void` | — | Value change callback |
+
+`collapsible` does not apply in multiple mode.
+
+### `AccordionItem` props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value` | `string` | **required** | Stable item id |
+| `disabled` | `boolean` | `false` | Disables this item |
+| `class` / other attrs | — | — | Forwarded to the item root |
+
+### `AccordionTrigger` props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `disabled` | `boolean` | inherits | Disables this trigger |
+| `class` / other attrs | — | — | Forwarded to the native `<button>` |
+
+Keyboard: Arrow Up/Down, Home, End.
+
+### `AccordionContent` props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `forceMount` | `boolean` | `false` | Keep content mounted while closed |
+| `class` / `style` | — | — | Applied to the inner clipped wrapper |
+| other attrs | — | — | Forwarded to the inner wrapper |
+
+### Multiple mode example
+
+```svelte
+<Accordion type="multiple" defaultValue={["general"]}>
+  <AccordionItem value="general">
+    <AccordionTrigger>General</AccordionTrigger>
+    <AccordionContent>General content</AccordionContent>
+  </AccordionItem>
+  <AccordionItem value="advanced">
+    <AccordionTrigger>Advanced</AccordionTrigger>
+    <AccordionContent>Advanced content</AccordionContent>
+  </AccordionItem>
+</Accordion>
+```
+
+### Accordion with custom animation
+
+```svelte
+<Accordion
+  type="single"
+  collapsible
+  animationTimingFunction="ease-in-out"
+  animationDuration={300}
+  animationDelay={0}
+>
+  ...
+</Accordion>
+```
+
+## Styling hooks
+
+| Attribute | Where | Purpose |
+| --- | --- | --- |
+| `data-slot` | root / trigger / content | Target parts in CSS |
+| `data-state` | `"open" \| "closed"` | Open/closed styling |
+| `data-disabled` | when disabled | Disabled styling |
+| `data-collapsible-content-wrapper` | inner panel | Borders, padding, backgrounds |
+| `data-animated` | content viewport | Present when height animation is active |
+
+## AI Agent Skill
+
+Practical Svelte usage for AI coding agents: [disclosure-svelte skill](https://github.com/zealakit/disclosure/blob/main/skills/disclosure-svelte.md).
+
+## License
+
+MIT © Zealakit

package/dist/accordion-content.svelte

@@ -0,0 +1,79 @@
+<script lang="ts">
+import { onMount } from "svelte";
+import {
+  getAccordionContext,
+  getAccordionItemContext,
+} from "./accordion-context.js";
+import { getCollapsibleAnimationStyleText } from "./animation.js";
+import { ensureCollapsibleStyles } from "./collapsible-styles.js";
+import { createPresence } from "./use-presence.svelte.js";
+
+type Props = {
+  forceMount?: boolean;
+  children?: import("svelte").Snippet;
+  class?: string;
+  id?: string;
+  style?: string | null;
+  ontransitionend?: (event: TransitionEvent) => void;
+  [key: string]: unknown;
+};
+
+let {
+  forceMount = false,
+  children,
+  class: className,
+  id,
+  style,
+  ontransitionend,
+  ...rest
+}: Props = $props();
+
+const accordion = getAccordionContext();
+const item = getAccordionItemContext();
+const presence = createPresence({
+  open: () => item.open,
+  animated: () => accordion.animated,
+  forceMount: () => forceMount,
+});
+
+const animationStyle = $derived(
+  getCollapsibleAnimationStyleText({
+    animationTimingFunction: accordion.animationTimingFunction,
+    animationDuration: accordion.animationDuration,
+    animationDelay: accordion.animationDelay,
+  }),
+);
+
+onMount(() => {
+  ensureCollapsibleStyles();
+});
+
+function handleTransitionEnd(event: TransitionEvent) {
+  ontransitionend?.(event);
+  presence.onTransitionEnd(event);
+}
+</script>
+
+{#if presence.mounted}
+  <section
+    id={id ?? item.contentId}
+    aria-labelledby={item.triggerId}
+    data-slot="accordion-content"
+    data-state={presence.present ? "open" : "closed"}
+    data-animated={presence.animated ? "" : undefined}
+    hidden={!presence.present && !presence.animated}
+    inert={!item.open ? true : undefined}
+    style={animationStyle}
+    ontransitionend={handleTransitionEnd}
+  >
+    <div
+      {...rest}
+      class={className}
+      {style}
+      data-collapsible-content-wrapper=""
+      data-state={presence.present ? "open" : "closed"}
+    >
+      {@render children?.()}
+    </div>
+  </section>
+{/if}

package/dist/accordion-content.svelte.d.ts

@@ -0,0 +1,12 @@
+type Props = {
+    forceMount?: boolean;
+    children?: import("svelte").Snippet;
+    class?: string;
+    id?: string;
+    style?: string | null;
+    ontransitionend?: (event: TransitionEvent) => void;
+    [key: string]: unknown;
+};
+declare const AccordionContent: import("svelte").Component<Props, {}, "">;
+type AccordionContent = ReturnType<typeof AccordionContent>;
+export default AccordionContent;

package/dist/accordion-context.d.ts

@@ -0,0 +1,26 @@
+import type { AnimationTimingFunction } from "./animation.js";
+export type AccordionContextValue = {
+    get type(): "single" | "multiple";
+    get animated(): boolean;
+    get animationTimingFunction(): AnimationTimingFunction;
+    get animationDuration(): number;
+    get animationDelay(): number;
+    get disabled(): boolean;
+    get collapsible(): boolean;
+    isItemOpen: (value: string) => boolean;
+    toggleItem: (value: string) => void;
+    registerTrigger: (value: string, node: HTMLButtonElement | null) => void;
+    getEnabledTriggerValues: () => string[];
+    focusTrigger: (value: string) => void;
+};
+export type AccordionItemContextValue = {
+    get value(): string;
+    get open(): boolean;
+    get disabled(): boolean;
+    contentId: string;
+    triggerId: string;
+};
+export declare function setAccordionContext(value: AccordionContextValue): void;
+export declare function getAccordionContext(): AccordionContextValue;
+export declare function setAccordionItemContext(value: AccordionItemContextValue): void;
+export declare function getAccordionItemContext(): AccordionItemContextValue;

package/dist/accordion-context.js

@@ -0,0 +1,23 @@
+import { getContext, setContext } from "svelte";
+const ACCORDION_CONTEXT = Symbol("zealakit-accordion");
+const ACCORDION_ITEM_CONTEXT = Symbol("zealakit-accordion-item");
+export function setAccordionContext(value) {
+    setContext(ACCORDION_CONTEXT, value);
+}
+export function getAccordionContext() {
+    const context = getContext(ACCORDION_CONTEXT);
+    if (!context) {
+        throw new Error("Accordion components must be used within an <Accordion>");
+    }
+    return context;
+}
+export function setAccordionItemContext(value) {
+    setContext(ACCORDION_ITEM_CONTEXT, value);
+}
+export function getAccordionItemContext() {
+    const context = getContext(ACCORDION_ITEM_CONTEXT);
+    if (!context) {
+        throw new Error("AccordionItem parts must be used within an <AccordionItem>");
+    }
+    return context;
+}

package/dist/accordion-item.svelte

@@ -0,0 +1,52 @@
+<script lang="ts">
+import {
+  getAccordionContext,
+  setAccordionItemContext,
+} from "./accordion-context.js";
+
+type Props = {
+  value: string;
+  disabled?: boolean;
+  children?: import("svelte").Snippet;
+  class?: string;
+  [key: string]: unknown;
+};
+
+let {
+  value,
+  disabled: disabledProp,
+  children,
+  class: className,
+  ...rest
+}: Props = $props();
+
+const accordion = getAccordionContext();
+const instanceId = crypto.randomUUID();
+
+const open = $derived(accordion.isItemOpen(value));
+const disabled = $derived(Boolean(accordion.disabled || disabledProp));
+
+setAccordionItemContext({
+  get value() {
+    return value;
+  },
+  get open() {
+    return open;
+  },
+  get disabled() {
+    return disabled;
+  },
+  triggerId: `accordion-trigger-${instanceId}`,
+  contentId: `accordion-content-${instanceId}`,
+});
+</script>
+
+<div
+  {...rest}
+  class={className}
+  data-slot="accordion-item"
+  data-state={open ? "open" : "closed"}
+  data-disabled={disabled ? "" : undefined}
+>
+  {@render children?.()}
+</div>

package/dist/accordion-item.svelte.d.ts

@@ -0,0 +1,10 @@
+type Props = {
+    value: string;
+    disabled?: boolean;
+    children?: import("svelte").Snippet;
+    class?: string;
+    [key: string]: unknown;
+};
+declare const AccordionItem: import("svelte").Component<Props, {}, "">;
+type AccordionItem = ReturnType<typeof AccordionItem>;
+export default AccordionItem;

package/dist/accordion-trigger.svelte

@@ -0,0 +1,111 @@
+<script lang="ts">
+import {
+  getAccordionContext,
+  getAccordionItemContext,
+} from "./accordion-context.js";
+
+type Props = {
+  disabled?: boolean;
+  children?: import("svelte").Snippet;
+  class?: string;
+  id?: string;
+  onclick?: (event: MouseEvent) => void;
+  onkeydown?: (event: KeyboardEvent) => void;
+  [key: string]: unknown;
+};
+
+let {
+  disabled: disabledProp,
+  children,
+  class: className,
+  id,
+  onclick,
+  onkeydown,
+  ...rest
+}: Props = $props();
+
+const accordion = getAccordionContext();
+const item = getAccordionItemContext();
+
+const isDisabled = $derived(disabledProp ?? item.disabled);
+
+let node = $state<HTMLButtonElement | null>(null);
+
+$effect(() => {
+  const element = node;
+  if (!element || isDisabled) {
+    return;
+  }
+  const itemValue = item.value;
+  accordion.registerTrigger(itemValue, element);
+  return () => {
+    accordion.registerTrigger(itemValue, null);
+  };
+});
+
+function handleClick(event: MouseEvent) {
+  onclick?.(event);
+  if (event.defaultPrevented || isDisabled) {
+    return;
+  }
+  accordion.toggleItem(item.value);
+}
+
+function handleKeyDown(event: KeyboardEvent) {
+  onkeydown?.(event);
+  if (event.defaultPrevented || isDisabled) {
+    return;
+  }
+
+  const enabled = accordion.getEnabledTriggerValues();
+  const currentIndex = enabled.indexOf(item.value);
+  if (currentIndex === -1 || enabled.length === 0) {
+    return;
+  }
+
+  const focusAt = (index: number) => {
+    const next = enabled[index];
+    if (next) {
+      event.preventDefault();
+      accordion.focusTrigger(next);
+    }
+  };
+
+  switch (event.key) {
+    case "ArrowDown":
+      focusAt((currentIndex + 1) % enabled.length);
+      break;
+    case "ArrowUp":
+      focusAt((currentIndex - 1 + enabled.length) % enabled.length);
+      break;
+    case "Home":
+      focusAt(0);
+      break;
+    case "End":
+      focusAt(enabled.length - 1);
+      break;
+    default:
+      break;
+  }
+}
+</script>
+
+<h3 data-slot="accordion-heading">
+  <button
+    type="button"
+    {...rest}
+    bind:this={node}
+    id={id ?? item.triggerId}
+    class={className}
+    aria-expanded={item.open}
+    aria-controls={item.contentId}
+    disabled={isDisabled}
+    data-slot="accordion-trigger"
+    data-state={item.open ? "open" : "closed"}
+    data-disabled={isDisabled ? "" : undefined}
+    onclick={handleClick}
+    onkeydown={handleKeyDown}
+  >
+    {@render children?.()}
+  </button>
+</h3>

package/dist/accordion-trigger.svelte.d.ts

@@ -0,0 +1,12 @@
+type Props = {
+    disabled?: boolean;
+    children?: import("svelte").Snippet;
+    class?: string;
+    id?: string;
+    onclick?: (event: MouseEvent) => void;
+    onkeydown?: (event: KeyboardEvent) => void;
+    [key: string]: unknown;
+};
+declare const AccordionTrigger: import("svelte").Component<Props, {}, "">;
+type AccordionTrigger = ReturnType<typeof AccordionTrigger>;
+export default AccordionTrigger;

package/dist/accordion-types.d.ts

@@ -0,0 +1,54 @@
+import type { CollapsibleAnimationProps } from "./animation.js";
+export type { AnimationTimingFunction, CollapsibleAnimationProps, } from "./animation.js";
+type AccordionSharedProps = CollapsibleAnimationProps & {
+    /**
+     * Whether the entire accordion ignores user interaction.
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Additional attributes forwarded to the root element.
+     */
+    [key: string]: unknown;
+};
+export type AccordionSingleProps = AccordionSharedProps & {
+    type?: "single";
+    /**
+     * Controlled value. Use `bind:value` for two-way binding.
+     */
+    value?: string | null;
+    defaultValue?: string | null;
+    /**
+     * Allow collapsing the open item in single mode.
+     * @default false
+     */
+    collapsible?: boolean;
+    onValueChange?: (value: string | null) => void;
+};
+export type AccordionMultipleProps = AccordionSharedProps & {
+    type: "multiple";
+    /**
+     * Controlled value. Use `bind:value` for two-way binding.
+     */
+    value?: string[];
+    defaultValue?: string[];
+    onValueChange?: (value: string[]) => void;
+};
+export type AccordionProps = AccordionSingleProps | AccordionMultipleProps;
+export type AccordionItemProps = {
+    value: string;
+    disabled?: boolean;
+    [key: string]: unknown;
+};
+export type AccordionTriggerProps = {
+    disabled?: boolean;
+    [key: string]: unknown;
+};
+export type AccordionContentProps = {
+    /**
+     * Keep content mounted while closed.
+     * @default false
+     */
+    forceMount?: boolean;
+    [key: string]: unknown;
+};

package/dist/accordion-types.js

@@ -0,0 +1 @@
+export {};