svseeds 0.5.3 → 0.7.1

package/README.md

@@ -1,7 +1,7 @@
 # SvSeeds - Simple Components for Svelte
 
 [![npm version](https://img.shields.io/npm/v/svseeds)](https://www.npmjs.com/package/svseeds)
-[![JSR](https://jsr.io/badges/@svseeds/ui)](https://jsr.io/@svseeds/ui)
+[![JSR Version](https://img.shields.io/jsr/v/%40svseeds/ui)](https://jsr.io/@svseeds/ui)
 [![license](https://img.shields.io/npm/l/svseeds)](LICENSE.md)
 
 SvSeeds is a collection of essential functional components for Svelte development. These components are intentionally designed with minimal styling, giving you complete freedom to apply your own styles based on your project requirements. For specialized needs, you can download the components as .svelte files through our CLI tool and customize their functionality directly.

package/_svseeds/Accordion.svelte

@@ -1,123 +1,159 @@
 <!--
   @component
+  ### Usage
+  Wrap one or more `Disclosure` children.
+  ```svelte
+  <Accordion {...props}>
+    <Disclosure label="Section 1" {...props}>Content</Disclosure>
+    <Disclosure label="Section 2" {...props}>Content</Disclosure>
+  </Accordion>
+  ```
   ### Types
   default value: *`(value)`*
   ```ts
   interface AccordionProps {
-    labels?: string[];
-    current?: number; // bindable (-1)
+    items?: AccordionItem[];
+    children?: Snippet;
+    current?: string; // bindable, undefined = all closed
     styling?: SVSClass;
-    variant?: string; // bindable (VARIANT.NEUTRAL)
-    deps?: AccordionDeps;
-    [key: string]: unknown | Snippet; // labels or contents of each disclosure
-  }
-  interface AccordionDeps {
-    svsDisclosure?: Omit<DisclosureProps, DisclosureReqdProps | DisclosureBindProps>;
+    variant?: SVSVariant; // (VARIANT.NEUTRAL)
+    disclosure?: Omit<DisclosureProps, DisclosureReqdProps | DisclosureBindProps | "id" | "inactive">;
   }
+  type AccordionComponent = { component: Component<any>; props?: Record<string, unknown> };
+  type AccordionItem = {
+    value: string; // REQUIRED, unique within `items`. Addresses `current`.
+    label: string | Snippet<[boolean, string]> | AccordionComponent;
+    panel: Snippet<[string]> | AccordionComponent;
+    disabled?: boolean; // (false)
+  };
   ```
+  `value`s must be unique within `items`. Accordion is exclusive: at most one item is open at a time.
+  Provide `items` for data mode or `children` for declarative mode; `children` wins when both are present.
   ### Anatomy
   ```svelte
-  <div class="whole">
-    {#each labels as label, i}
-      <Disclosure {label}>
-        {@render restProps[i]()}
-      </Disclosure>
-    {/each}
+  <div class="whole" role="group">
+    {#if children}
+      {children}
+    {:else}
+      {#each items as item}
+        <Disclosure id={item.value} label={item.label} inactive={item.disabled || undefined}>
+          {item.panel}
+        </Disclosure>
+      {/each}
+    {/if}
   </div>
   ```
+  Data-mode child styling defaults to the combined parent/child preset and can be customized via `disclosure`.
+  ### Behavior
+  Declarative `<Disclosure id=...>` children automatically coordinate exclusive open state through `current` and inherit the base `variant`/`styling`.
 -->
 <script module lang="ts">
   export interface AccordionProps {
-    labels?: string[];
-    current?: number; // bindable (-1)
+    items?: AccordionItem[];
+    children?: Snippet;
+    current?: string; // bindable, undefined = all closed
     styling?: SVSClass;
-    variant?: string; // bindable (VARIANT.NEUTRAL)
-    deps?: AccordionDeps;
-    [key: string]: unknown | Snippet; // labels or contents of each disclosure
-  }
-  export interface AccordionDeps {
-    svsDisclosure?: Omit<DisclosureProps, DisclosureReqdProps | DisclosureBindProps>;
+    variant?: SVSVariant; // (VARIANT.NEUTRAL)
+    disclosure?: Omit<DisclosureProps, DisclosureReqdProps | DisclosureBindProps | "id" | "inactive">;
   }
   export type AccordionReqdProps = never;
-  export type AccordionBindProps = "current" | "variant";
+  export type AccordionBindProps = "current";
+  export type AccordionComponent = { component: Component<any>; props?: Record<string, unknown> };
+  export type AccordionItem = {
+    value: string; // REQUIRED, unique within `items`. Addresses `current`.
+    label: string | Snippet<[boolean, string]> | AccordionComponent;
+    panel: Snippet<[string]> | AccordionComponent;
+    disabled?: boolean; // (false)
+  };
 
-  type NamedId = { id: string, name: string };
-  const preset = "svs-accordion";
-  const roleLabel = "label";
-  const rolePanel = "panel";
+  export const _ACCORDION_PRESET = "svs-accordion";
 
-  function getSnippetNames(role: string, rest: Record<string, unknown>): string[] {
-    return Object.keys(rest)
-      .filter((x) => x.startsWith(role) && typeof rest[x] === "function")
-      .toSorted((x,y) => x.localeCompare(y));
-  }
-  function toNamedId(names: string[]): NamedId[] {
-    return names.map((x) => ({ id: elemId.id, name: x }));
+  function isComponent(x: unknown): x is AccordionComponent {
+    return typeof x === "object" && x !== null && "component" in x;
   }
 
-  import { type Snippet, untrack } from "svelte";
-  import { type SVSClass, VARIANT, PARTS, elemId, fnClass, omit } from "./core";
-  import Disclosure, { type DisclosureProps, type DisclosureReqdProps, type DisclosureBindProps } from "./_Disclosure.svelte";
+  import { untrack } from "svelte";
+  import { VARIANT, PARTS, _fnClass, _omit } from "./_core";
+  import Disclosure, { _DISCLOSURE_PRESET, _setDisclosureContext } from "./Disclosure.svelte";
+  import type { Component, Snippet } from "svelte";
+  import type { SVSClass, SVSVariant } from "./_core";
+  import type { DisclosureContext, DisclosureProps, DisclosureReqdProps, DisclosureBindProps } from "./Disclosure.svelte";
 </script>
 
 <script lang="ts">
-  let { labels = [], current = $bindable(-1), styling, variant = $bindable(""), deps, ...rest }: AccordionProps = $props();
+  // prettier-ignore
+  let { items, children, current = $bindable<string | undefined>(), styling, variant = VARIANT.NEUTRAL, disclosure }: AccordionProps = $props();
 
   // *** Initialize *** //
-  if (!variant) variant = VARIANT.NEUTRAL;
-  const cls = fnClass(preset, styling);
-  const isStrLabel = labels.length > 0;
-  const lbls = toNamedId(isStrLabel ? labels : getSnippetNames(roleLabel, rest));
-  const panels = getSnippetNames(rolePanel, rest);
-  const isValidAccordion = lbls.length && panels.length && lbls.length === panels.length;
-  let guard = current >= 0 && current < lbls.length;
-  let event = false;
-  let opens = $state(Array(lbls.length).fill(false));
-  let elems: HTMLDetailsElement[] = $state([]);
-
-  // *** Initialize Deps *** //
-  const svsDisclosure = {
-    ...omit(deps?.svsDisclosure, "attributes", "styling"),
-    styling: deps?.svsDisclosure?.styling ?? `${preset} svs-disclosure`,
+  const cls = $derived(_fnClass(_ACCORDION_PRESET, styling));
+  const ctxCurrent = $derived(current);
+  const ctxVariant = $derived(variant);
+  const ctxStyling = $derived(styling);
+  const ctx: DisclosureContext = {
+    get current() {
+      return ctxCurrent;
+    },
+    set current(v: string | undefined) {
+      current = v;
+    },
+    get variant() {
+      return ctxVariant;
+    },
+    get styling() {
+      return ctxStyling;
+    },
   };
+  _setDisclosureContext(ctx);
+  const selected = $derived(children || !items ? current : items.some((it) => it.value === current && !it.disabled) ? current : undefined);
 
-  // *** Bind Handlers *** //
-  $effect.pre(() => {
-    current;
-    untrack(() => toggle());
+  // *** Initialize Child Props *** //
+  const childProps = $derived({
+    ..._omit(disclosure, "styling"),
+    styling: disclosure?.styling ?? `${_ACCORDION_PRESET} ${_DISCLOSURE_PRESET}`,
   });
-  function toggle() {
-    if (!event) opens = opens.fill(false).map((_, i) => i === current);
-    event = false;
-  }
-  function setCurrent(index: number) {
-    current = index;
-    if (guard) return guard = false;
-    event = true;
-  }
 
-  // *** Event Handlers *** //
-  function exclusiveToggle(index: number): (ev: Event) => void {
-    return (ev) => {
-      deps?.svsDisclosure?.attributes?.ontoggle?.(ev as any);
-      if (opens.every((x) => !x)) return setCurrent(-1);
-      if (elems[index].open) {
-        opens = opens.map((_, i) => i === index);
-        setCurrent(index);
-      }
-    };
-  }
+  // *** Reactive Handlers *** //
+  $effect(() => {
+    if (current !== selected) untrack(() => (current = selected));
+  });
 </script>
 
 <!---------------------------------------->
 
-{#if isValidAccordion}
+{#if children}
   <div class={cls(PARTS.WHOLE, variant)} role="group">
-    {#each lbls as { id, name }, i (id)}
-      {@const ontoggle = exclusiveToggle(i)}
-      <Disclosure bind:open={opens[i]} bind:element={elems[i]} label={isStrLabel ? name : (rest[name] as Snippet)} attributes={{...deps?.svsDisclosure?.attributes, ontoggle}} {...svsDisclosure}>
-        {@render (rest[panels[i]] as Snippet)()}
-      </Disclosure>
+    {@render children()}
+  </div>
+{:else if items && items.length > 0}
+  <div class={cls(PARTS.WHOLE, variant)} role="group">
+    {#each items as item (item.value)}
+      {#snippet label(open: boolean, variant: string)}
+        {@render labelContent(item.label, open, variant)}
+      {/snippet}
+      {#snippet panel(variant: string)}
+        {@render panelContent(item.panel, variant)}
+      {/snippet}
+      <Disclosure id={item.value} {label} children={panel} inactive={item.disabled || undefined} {variant} {...childProps} />
     {/each}
   </div>
 {/if}
+
+{#snippet labelContent(c: string | Snippet<[boolean, string]> | AccordionComponent, open: boolean, variant: string)}
+  {#if typeof c === "string"}
+    {c}
+  {:else if isComponent(c)}
+    {@const C = c.component}
+    <C {...c.props} />
+  {:else}
+    {@render c(open, variant)}
+  {/if}
+{/snippet}
+
+{#snippet panelContent(c: Snippet<[string]> | AccordionComponent, variant: string)}
+  {#if isComponent(c)}
+    {@const C = c.component}
+    <C {...c.props} />
+  {:else}
+    {@render c(variant)}
+  {/if}
+{/snippet}

package/_svseeds/Accordion.svelte.d.ts

@@ -1,46 +1,75 @@
 export interface AccordionProps {
-    labels?: string[];
-    current?: number;
+    items?: AccordionItem[];
+    children?: Snippet;
+    current?: string;
     styling?: SVSClass;
-    variant?: string;
-    deps?: AccordionDeps;
-    [key: string]: unknown | Snippet;
-}
-export interface AccordionDeps {
-    svsDisclosure?: Omit<DisclosureProps, DisclosureReqdProps | DisclosureBindProps>;
+    variant?: SVSVariant;
+    disclosure?: Omit<DisclosureProps, DisclosureReqdProps | DisclosureBindProps | "id" | "inactive">;
 }
 export type AccordionReqdProps = never;
-export type AccordionBindProps = "current" | "variant";
-import { type Snippet } from "svelte";
-import { type SVSClass } from "./core";
-import { type DisclosureProps, type DisclosureReqdProps, type DisclosureBindProps } from "./_Disclosure.svelte";
+export type AccordionBindProps = "current";
+export type AccordionComponent = {
+    component: Component<any>;
+    props?: Record<string, unknown>;
+};
+export type AccordionItem = {
+    value: string;
+    label: string | Snippet<[boolean, string]> | AccordionComponent;
+    panel: Snippet<[string]> | AccordionComponent;
+    disabled?: boolean;
+};
+export declare const _ACCORDION_PRESET = "svs-accordion";
+import type { Component, Snippet } from "svelte";
+import type { SVSClass, SVSVariant } from "./_core";
+import type { DisclosureProps, DisclosureReqdProps, DisclosureBindProps } from "./Disclosure.svelte";
 /**
+ * ### Usage
+ * Wrap one or more `Disclosure` children.
+ * ```svelte
+ * <Accordion {...props}>
+ *   <Disclosure label="Section 1" {...props}>Content</Disclosure>
+ *   <Disclosure label="Section 2" {...props}>Content</Disclosure>
+ * </Accordion>
+ * ```
  * ### Types
  * default value: *`(value)`*
  * ```ts
  * interface AccordionProps {
- *   labels?: string[];
- *   current?: number; // bindable (-1)
+ *   items?: AccordionItem[];
+ *   children?: Snippet;
+ *   current?: string; // bindable, undefined = all closed
  *   styling?: SVSClass;
- *   variant?: string; // bindable (VARIANT.NEUTRAL)
- *   deps?: AccordionDeps;
- *   [key: string]: unknown | Snippet; // labels or contents of each disclosure
- * }
- * interface AccordionDeps {
- *   svsDisclosure?: Omit<DisclosureProps, DisclosureReqdProps | DisclosureBindProps>;
+ *   variant?: SVSVariant; // (VARIANT.NEUTRAL)
+ *   disclosure?: Omit<DisclosureProps, DisclosureReqdProps | DisclosureBindProps | "id" | "inactive">;
  * }
+ * type AccordionComponent = { component: Component<any>; props?: Record<string, unknown> };
+ * type AccordionItem = {
+ *   value: string; // REQUIRED, unique within `items`. Addresses `current`.
+ *   label: string | Snippet<[boolean, string]> | AccordionComponent;
+ *   panel: Snippet<[string]> | AccordionComponent;
+ *   disabled?: boolean; // (false)
+ * };
  * ```
+ * `value`s must be unique within `items`. Accordion is exclusive: at most one item is open at a time.
+ * Provide `items` for data mode or `children` for declarative mode; `children` wins when both are present.
  * ### Anatomy
  * ```svelte
- * <div class="whole">
- *   {#each labels as label, i}
- *     <Disclosure {label}>
- *       {@render restProps[i]()}
- *     </Disclosure>
- *   {/each}
+ * <div class="whole" role="group">
+ *   {#if children}
+ *     {children}
+ *   {:else}
+ *     {#each items as item}
+ *       <Disclosure id={item.value} label={item.label} inactive={item.disabled || undefined}>
+ *         {item.panel}
+ *       </Disclosure>
+ *     {/each}
+ *   {/if}
  * </div>
  * ```
+ * Data-mode child styling defaults to the combined parent/child preset and can be customized via `disclosure`.
+ * ### Behavior
+ * Declarative `<Disclosure id=...>` children automatically coordinate exclusive open state through `current` and inherit the base `variant`/`styling`.
  */
-declare const Accordion: import("svelte").Component<AccordionProps, {}, "variant" | "current">;
+declare const Accordion: Component<AccordionProps, {}, "current">;
 type Accordion = ReturnType<typeof Accordion>;
 export default Accordion;

package/_svseeds/Button.svelte

@@ -0,0 +1,116 @@
+<!--
+  @component
+  ### Usage
+  Use standalone.
+  ```svelte
+  <Button {...props}>Label</Button>
+  ```
+  ### Types
+  default value: *`(value)`*
+  ```ts
+  interface ButtonProps extends Omit<HTMLButtonAttributes, "children" | "form" | "type" | "onclick"> {
+    children: Snippet<[string]>; // Snippet<[variant]>
+    left?: Snippet<[string, HTMLButtonElement | undefined]>; // Snippet<[variant,element]>
+    right?: Snippet<[string, HTMLButtonElement | undefined]>; // Snippet<[variant,element]>
+    type?: "submit" | "reset" | "button"; // ("button")
+    onclick?: MouseEventHandler<HTMLButtonElement> | null;
+    form?: HTMLFormElement;
+    inactive?: string; // reason; when set: aria-disabled + aria-description, variant->INACTIVE, onclick suppressed
+    attach?: Attachment<HTMLButtonElement>;
+    element?: HTMLButtonElement; // bindable
+    styling?: SVSClass;
+    variant?: SVSVariant; // bindable (VARIANT.NEUTRAL)
+    // other HTMLButtonAttributes are passed to <button> via ...rest; `class` is merged onto root <button>
+  }
+  ```
+  ### Anatomy
+  ```svelte
+  <button class="whole" {...rest} {type} {onclick} aria-disabled aria-description>
+    <span class="left" conditional>{left}</span>
+    <span class="main">{children}</span>
+    <span class="right" conditional>{right}</span>
+  </button>
+  ```
+-->
+<script module lang="ts">
+  export interface ButtonProps extends Omit<HTMLButtonAttributes, "children" | "form" | "type"> {
+    children: Snippet<[string]>; // Snippet<[variant]>
+    left?: Snippet<[string, HTMLButtonElement | undefined]>; // Snippet<[variant,element]>
+    right?: Snippet<[string, HTMLButtonElement | undefined]>; // Snippet<[variant,element]>
+    type?: "submit" | "reset" | "button"; // ("button")
+    form?: HTMLFormElement;
+    inactive?: string; // reason; when set: aria-disabled + aria-description, variant->INACTIVE, onclick suppressed
+    attach?: Attachment<HTMLButtonElement>;
+    element?: HTMLButtonElement; // bindable
+    styling?: SVSClass;
+    variant?: SVSVariant; // bindable (VARIANT.NEUTRAL)
+  }
+  export type ButtonReqdProps = "children";
+  export type ButtonBindProps = "element" | "variant";
+
+  export const _BUTTON_PRESET = "svs-button";
+
+  import { VARIANT, PARTS, _fnClass } from "./_core";
+  import type { Snippet } from "svelte";
+  import type { Attachment } from "svelte/attachments";
+  import type { HTMLButtonAttributes, MouseEventHandler } from "svelte/elements";
+  import type { SVSClass, SVSVariant } from "./_core";
+</script>
+
+<script lang="ts">
+  // prettier-ignore
+  let { children, left, right, type = "button", onclick, form, attach, element = $bindable(), styling, variant = $bindable(VARIANT.NEUTRAL), inactive, class: c, ...rest }: ButtonProps = $props();
+
+  // *** Initialize *** //
+  const cls = $derived(_fnClass(_BUTTON_PRESET, styling));
+  const idForm = $derived(form?.id || undefined);
+  const reason = $derived(inactive?.trim() ? inactive : undefined);
+  const inactiveAttrs = $derived(reason ? { "aria-disabled": true, "aria-description": reason } : {});
+
+  let prevVariant: SVSVariant | undefined;
+  $effect(() => {
+    if (reason) {
+      if (variant !== VARIANT.INACTIVE) {
+        prevVariant = variant;
+        variant = VARIANT.INACTIVE;
+      }
+    } else if (prevVariant !== undefined) {
+      variant = prevVariant;
+      prevVariant = undefined;
+    }
+  });
+
+  // *** Event Handlers *** //
+  const hclick: MouseEventHandler<HTMLButtonElement> = (ev) => {
+    if (reason) return;
+    if (form?.checkValidity() ?? true) onclick?.(ev);
+  };
+</script>
+
+<!---------------------------------------->
+
+<button
+  bind:this={element}
+  class={[cls(PARTS.WHOLE, variant), c]}
+  {type}
+  onclick={hclick}
+  form={idForm}
+  {...rest}
+  {...inactiveAttrs}
+  {@attach attach}
+>
+  {@render whole()}
+</button>
+
+{#snippet side(area: string, body?: Snippet<[string, HTMLButtonElement | undefined]>)}
+  {#if body}
+    <span class={cls(area, variant)}>{@render body(variant, element)}</span>
+  {/if}
+{/snippet}
+{#snippet whole()}
+  {@render side(PARTS.LEFT, left)}
+  <span class={cls(PARTS.MAIN, variant)}>
+    {@render children(variant)}
+  </span>
+  {@render side(PARTS.RIGHT, right)}
+{/snippet}

package/_svseeds/Button.svelte.d.ts

@@ -0,0 +1,55 @@
+export interface ButtonProps extends Omit<HTMLButtonAttributes, "children" | "form" | "type"> {
+    children: Snippet<[string]>;
+    left?: Snippet<[string, HTMLButtonElement | undefined]>;
+    right?: Snippet<[string, HTMLButtonElement | undefined]>;
+    type?: "submit" | "reset" | "button";
+    form?: HTMLFormElement;
+    inactive?: string;
+    attach?: Attachment<HTMLButtonElement>;
+    element?: HTMLButtonElement;
+    styling?: SVSClass;
+    variant?: SVSVariant;
+}
+export type ButtonReqdProps = "children";
+export type ButtonBindProps = "element" | "variant";
+export declare const _BUTTON_PRESET = "svs-button";
+import type { Snippet } from "svelte";
+import type { Attachment } from "svelte/attachments";
+import type { HTMLButtonAttributes } from "svelte/elements";
+import type { SVSClass, SVSVariant } from "./_core";
+/**
+ * ### Usage
+ * Use standalone.
+ * ```svelte
+ * <Button {...props}>Label</Button>
+ * ```
+ * ### Types
+ * default value: *`(value)`*
+ * ```ts
+ * interface ButtonProps extends Omit<HTMLButtonAttributes, "children" | "form" | "type" | "onclick"> {
+ *   children: Snippet<[string]>; // Snippet<[variant]>
+ *   left?: Snippet<[string, HTMLButtonElement | undefined]>; // Snippet<[variant,element]>
+ *   right?: Snippet<[string, HTMLButtonElement | undefined]>; // Snippet<[variant,element]>
+ *   type?: "submit" | "reset" | "button"; // ("button")
+ *   onclick?: MouseEventHandler<HTMLButtonElement> | null;
+ *   form?: HTMLFormElement;
+ *   inactive?: string; // reason; when set: aria-disabled + aria-description, variant->INACTIVE, onclick suppressed
+ *   attach?: Attachment<HTMLButtonElement>;
+ *   element?: HTMLButtonElement; // bindable
+ *   styling?: SVSClass;
+ *   variant?: SVSVariant; // bindable (VARIANT.NEUTRAL)
+ *   // other HTMLButtonAttributes are passed to <button> via ...rest; `class` is merged onto root <button>
+ * }
+ * ```
+ * ### Anatomy
+ * ```svelte
+ * <button class="whole" {...rest} {type} {onclick} aria-disabled aria-description>
+ *   <span class="left" conditional>{left}</span>
+ *   <span class="main">{children}</span>
+ *   <span class="right" conditional>{right}</span>
+ * </button>
+ * ```
+ */
+declare const Button: import("svelte").Component<ButtonProps, {}, "variant" | "element">;
+type Button = ReturnType<typeof Button>;
+export default Button;