@stubber/form-fields 2.2.6 → 3.0.0

package/README.md

@@ -1,38 +1,76 @@
 # stubber-form-fields-pkg
 
-## How to use
+This package provides a set of Svelte components for building accessible, composable form fields from json definitions.
 
-```
-git clone git@github.com:stubber/stubber-public-form-fields-pkg.git form-fields-pkg
-cd form-fields-pkg
-cp .env_staging .env
-pnpm install
-pnpm run dev
-```
+## Consumer styling contract
 
-# Publishing
+The package owns the structural CSS that fields need to function, including layout, spacing,
+sizing, alignment, overlays, and disclosure movement. Consumers own the visual theme and provide
+classes for semantic roles through the `Form` component's `styles` prop.
 
-We use [semantic-release](https://github.com/semantic-release/semantic-release) to automate the versioning and package publishing process. To publish a new version of the package, follow these steps:
+`FormFieldStyles` is a flat set of class hooks. A class string is added directly to every element
+with that role, alongside the package's internal structural class. All properties are optional;
+the package does not supply or merge a default visual theme, and an omitted role receives no
+consumer class. Pass the styles once at the outer form boundary; nested forms inherit them.
 
-Simply make a commit with a message that follows the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification, and push it to the master branch. The commit message should include a type (feat, fix, chore, etc.) and an optional scope.
+```svelte
+<script lang="ts">
+  import { Form, type FormFieldStyles } from "@stubber/form-fields";
 
-For example:
+  const styles: FormFieldStyles = {
+    label: "text-sm font-medium",
+    message: "text-xs text-slate-500 data-[variant=error]:text-red-600",
+    input: "w-full rounded border px-3 py-2",
+    choice: "size-4 accent-blue-600",
+    range: "w-full accent-blue-600",
+    group: "rounded border p-3 data-[invalid]:border-red-600",
+    dropzone: "rounded border-2 border-dashed p-4 data-[dragging]:border-blue-600",
+    uploadItem: "rounded border bg-slate-50 p-2",
+    popover: "rounded border bg-white p-1 shadow-md",
+    option:
+      "px-2 py-1 data-[highlighted]:bg-blue-600 data-[highlighted]:text-white aria-[selected=true]:font-semibold",
+    button:
+      "rounded px-2 py-1 data-[variant=primary]:bg-blue-600 data-[variant=primary]:text-white data-[variant=destructive]:bg-red-600 data-[variant=destructive]:text-white data-[size=icon]:size-8 data-[size=icon]:p-0",
+  };
+</script>
 
-```bash
-# will create a new major release.
-breaking: change button color to red
-feat!: add new button component
+<Form {styles} {form} {initial_form} />
+```
 
-# will create a new minor release.
-feat: add new button component
+The supported roles are:
 
-# will create a new patch release.
-fix: fix button color
-```
+| Role         | Applied to                                                                                             |
+| ------------ | ------------------------------------------------------------------------------------------------------ |
+| `label`      | Field labels and section/group legends                                                                 |
+| `input`      | Text-like controls, including text areas, number/date inputs, autocomplete inputs, and editor surfaces |
+| `choice`     | Checkboxes, radio buttons, and other binary or multiple-choice controls                                |
+| `range`      | Range/slider inputs                                                                                    |
+| `message`    | Help and validation messages                                                                           |
+| `group`      | Section and grouped-field containers                                                                   |
+| `dropzone`   | File upload dropzones                                                                                  |
+| `uploadItem` | Uploaded, recorded, or captured file items                                                             |
+| `popover`    | Option lists, popovers, and dialogs                                                                    |
+| `option`     | Individual options in a choice list                                                                    |
+| `button`     | Form actions, including add, remove, navigation, capture, and recording controls                       |
+
+### State selectors
 
-See default ruleset [here](https://github.com/semantic-release/commit-analyzer/blob/master/lib/default-release-rules.js)
+Use native selectors where the state has an HTML or ARIA equivalent: `:disabled`,
+`[aria-invalid="true"]`, and `[aria-selected="true"]`. The package exposes the remaining visual
+states as attributes:
 
-# Quick Testing
+| Role       | Attribute          | Values/presence                            |
+| ---------- | ------------------ | ------------------------------------------ |
+| `message`  | `data-variant`     | `help`, `error`                            |
+| `group`    | `data-invalid`     | Present when invalid                       |
+| `dropzone` | `data-dragging`    | Present while dragging over the target     |
+| `dropzone` | `data-disabled`    | Present when the upload limit is reached   |
+| `dropzone` | `data-invalid`     | Present when invalid                       |
+| `option`   | `data-highlighted` | Present on the keyboard-highlighted option |
+| `button`   | `data-variant`     | `primary`, `destructive`                   |
+| `button`   | `data-size`        | `icon`                                     |
 
-A preview of all fields and some edge cases are available to test on the sveltekit app.  
-On staging, it's hosted at https://form-fields-pkg.staging.stubber.zone
+Button variant and size are independent, so a button may be both
+`data-variant="destructive"` and `data-size="icon"`. Treat the role names and state attributes above
+as the public styling API; internal package class names and DOM structure are implementation
+details and should not be targeted by consumer styles.

package/dist/form-fields/Autocomplete.svelte

@@ -0,0 +1,261 @@
+<script context="module"></script>
+
+<script>import { debounce, isEqual } from "lodash-es";
+import { createEventDispatcher, getContext, onDestroy, tick } from "svelte";
+import ChevronDownIcon from "./icons/ChevronDownIcon.svelte";
+import { STYLES_CONTEXT, classNames } from "./styles";
+export let id;
+export let options = [];
+export let value = void 0;
+export let placeholder = "Select...";
+export let emptyMessage = "No results found.";
+export let loadingMessage = "Loading\u2026";
+export let ariaLabel = void 0;
+export let ariaDescribedby = void 0;
+export let invalid = false;
+export let inputClass = void 0;
+export let variant = "default";
+export let loadOptions = void 0;
+export let selected = (option, value2) => isEqual(option.value, value2);
+const styles = getContext(STYLES_CONTEXT);
+const dispatch = createEventDispatcher();
+let open = false;
+let loading = false;
+let query = "";
+let highlightedIndex = 0;
+let inputElement;
+let listElement;
+let availableOptions = options;
+let requestId = 0;
+$: if (!loadOptions) availableOptions = options;
+$: selectedLabel = availableOptions.find((option) => selected(option, value))?.label ?? placeholder;
+$: if (!open) query = selectedLabel;
+$: visibleOptions = loadOptions ? availableOptions : availableOptions.filter(
+  (option) => (option.searchText ?? option.label).toLowerCase().includes(query.trim().toLowerCase())
+);
+$: if (highlightedIndex >= visibleOptions.length) {
+  highlightedIndex = Math.max(visibleOptions.length - 1, 0);
+}
+$: if (open && listElement && visibleOptions[highlightedIndex]) {
+  const index = highlightedIndex;
+  void tick().then(() => {
+    if (open && index === highlightedIndex) {
+      listElement.children[index]?.scrollIntoView({
+        block: "nearest",
+        inline: "nearest"
+      });
+    }
+  });
+}
+const search = async (searchTerm) => {
+  if (!loadOptions) return;
+  const currentRequest = ++requestId;
+  loading = true;
+  try {
+    const results = await loadOptions(searchTerm);
+    if (currentRequest !== requestId) return;
+    availableOptions = results;
+    highlightedIndex = 0;
+  } finally {
+    if (currentRequest === requestId) loading = false;
+  }
+};
+const debouncedSearch = debounce(search, 300);
+onDestroy(() => debouncedSearch.cancel());
+function openList() {
+  if (open) return;
+  open = true;
+  query = "";
+  highlightedIndex = Math.max(
+    availableOptions.findIndex((option) => selected(option, value)),
+    0
+  );
+  if (loadOptions) void search("");
+}
+function closeList() {
+  open = false;
+  query = selectedLabel;
+}
+function choose(option) {
+  dispatch("select", option);
+  inputElement.focus();
+  closeList();
+}
+function handleInput(event) {
+  query = event.currentTarget.value;
+  open = true;
+  highlightedIndex = 0;
+  if (loadOptions) debouncedSearch(query);
+}
+function handleKeydown(event) {
+  if (event.key === "ArrowDown") {
+    event.preventDefault();
+    openList();
+    highlightedIndex = Math.min(highlightedIndex + 1, visibleOptions.length - 1);
+  } else if (event.key === "ArrowUp") {
+    event.preventDefault();
+    openList();
+    highlightedIndex = Math.max(highlightedIndex - 1, 0);
+  } else if (event.key === "Enter" && open && visibleOptions[highlightedIndex]) {
+    event.preventDefault();
+    choose(visibleOptions[highlightedIndex]);
+  } else if (event.key === "Escape" && open) {
+    event.preventDefault();
+    closeList();
+  }
+}
+function handleFocusout(event) {
+  const nextTarget = event.relatedTarget;
+  const currentTarget = event.currentTarget;
+  if (!(nextTarget instanceof Node) || !currentTarget.contains(nextTarget)) closeList();
+}
+function optionKey(option, index) {
+  return option.key ?? `${option.label}-${index}`;
+}
+</script>
+
+<div class="autocomplete" data-variant={variant} on:focusout={handleFocusout}>
+  <div class="autocomplete-input-wrapper" aria-invalid={invalid ? true : undefined}>
+    <input
+      bind:this={inputElement}
+      {id}
+      class={classNames("autocomplete-input", inputClass, variant === "default" && $styles.input)}
+      data-variant={variant === "embedded" ? "embedded" : undefined}
+      type="text"
+      role="combobox"
+      autocomplete="off"
+      value={query}
+      {placeholder}
+      aria-label={ariaLabel}
+      aria-autocomplete="list"
+      aria-expanded={open}
+      aria-controls="autocomplete-listbox-{id}"
+      aria-activedescendant={open && visibleOptions[highlightedIndex]
+        ? `autocomplete-option-${id}-${highlightedIndex}`
+        : undefined}
+      aria-invalid={invalid ? true : undefined}
+      aria-describedby={ariaDescribedby}
+      on:focus={openList}
+      on:click={openList}
+      on:input={handleInput}
+      on:keydown={handleKeydown}
+    />
+    <span class:open class="autocomplete-indicator" aria-hidden="true">
+      <ChevronDownIcon />
+    </span>
+  </div>
+
+  {#if open}
+    <ul
+      bind:this={listElement}
+      id="autocomplete-listbox-{id}"
+      class={classNames("autocomplete-options", $styles.popover)}
+      role="listbox"
+    >
+      {#if loading}
+        <li class="autocomplete-status" role="status">{loadingMessage}</li>
+      {:else if visibleOptions.length === 0}
+        <li class="autocomplete-status" role="status">{emptyMessage}</li>
+      {:else}
+        {#each visibleOptions as option, index (optionKey(option, index))}
+          <li role="presentation">
+            <button
+              id="autocomplete-option-{id}-{index}"
+              type="button"
+              role="option"
+              tabindex="-1"
+              aria-selected={selected(option, value)}
+              data-highlighted={index === highlightedIndex ? true : undefined}
+              class={classNames("autocomplete-option", $styles.option)}
+              on:mousedown={(event) => event.preventDefault()}
+              on:mouseenter={() => (highlightedIndex = index)}
+              on:click={() => choose(option)}
+            >
+              <slot name="option" {option}>{option.label}</slot>
+            </button>
+          </li>
+        {/each}
+      {/if}
+    </ul>
+  {/if}
+</div>
+
+<style>
+  .autocomplete {
+    position: relative;
+    box-sizing: border-box;
+    width: 100%;
+  }
+
+  .autocomplete-input-wrapper {
+    position: relative;
+    display: flex;
+    align-items: center;
+  }
+
+  .autocomplete-input {
+    box-sizing: border-box;
+    width: 100%;
+    padding-inline-end: 2rem;
+  }
+
+  .autocomplete-indicator {
+    position: absolute;
+    inset-inline-end: 0.5rem;
+    display: flex;
+    pointer-events: none;
+  }
+
+  .autocomplete-options {
+    position: absolute;
+    z-index: 20;
+    top: 100%;
+    box-sizing: border-box;
+    width: 100%;
+    max-height: 15rem;
+    overflow-y: auto;
+  }
+
+  :global(:where(.autocomplete-option)) {
+    -webkit-appearance: none;
+       -moz-appearance: none;
+            appearance: none;
+    box-sizing: border-box;
+    display: block;
+    width: 100%;
+    padding: 0;
+    border: 0;
+    background: transparent;
+    color: inherit;
+    font: inherit;
+    text-align: start;
+    cursor: pointer;
+  }
+
+  .autocomplete[data-variant="embedded"] {
+    width: 5.5rem;
+  }
+
+  .autocomplete[data-variant="embedded"] .autocomplete-input {
+    padding-inline-end: 0.5rem;
+    background: transparent;
+    color: inherit;
+  }
+
+  .autocomplete[data-variant="embedded"] .autocomplete-input:focus {
+    outline: none;
+  }
+
+  .autocomplete[data-variant="embedded"] .autocomplete-indicator {
+    inset-block: 0;
+    inset-inline-end: 0;
+    align-items: center;
+  }
+
+  .autocomplete[data-variant="embedded"] .autocomplete-options {
+    right: 0;
+    left: auto;
+    width: min(18rem, calc(100vw - 2rem));
+    max-height: 16rem;
+  }
+</style>

package/dist/form-fields/Autocomplete.svelte.d.ts

@@ -0,0 +1,43 @@
+import { SvelteComponent } from "svelte";
+export interface AutocompleteOption<T = any> {
+    label: string;
+    value: T;
+    key?: string;
+    searchText?: string;
+    [key: string]: any;
+}
+declare const __propDef: {
+    props: {
+        id: string;
+        options?: AutocompleteOption[];
+        value?: any;
+        placeholder?: string;
+        emptyMessage?: string;
+        loadingMessage?: string;
+        ariaLabel?: string | undefined;
+        ariaDescribedby?: string | undefined;
+        invalid?: boolean;
+        inputClass?: string | undefined;
+        variant?: "default" | "embedded";
+        loadOptions?: ((searchTerm: string) => Promise<AutocompleteOption[]>) | undefined;
+        selected?: (option: AutocompleteOption, value: any) => boolean;
+    };
+    events: {
+        select: CustomEvent<AutocompleteOption<any>>;
+    } & {
+        [evt: string]: CustomEvent<any>;
+    };
+    slots: {
+        option: {
+            option: AutocompleteOption<any>;
+        };
+    };
+    exports?: {} | undefined;
+    bindings?: string | undefined;
+};
+export type AutocompleteProps = typeof __propDef.props;
+export type AutocompleteEvents = typeof __propDef.events;
+export type AutocompleteSlots = typeof __propDef.slots;
+export default class Autocomplete extends SvelteComponent<AutocompleteProps, AutocompleteEvents, AutocompleteSlots> {
+}
+export {};

package/dist/form-fields/CollapsibleSection.svelte

@@ -0,0 +1,127 @@
+<script>import ChevronDownIcon from "./icons/ChevronDownIcon.svelte";
+export let title;
+export let open = false;
+export let contentId = void 0;
+export let labelledBy = void 0;
+export let onToggle = void 0;
+function toggle() {
+  open = !open;
+  onToggle?.(open);
+}
+</script>
+
+<div class="collapsible-section">
+  <div class="collapsible-section-header">
+    <button
+      type="button"
+      class="collapsible-section-toggle"
+      aria-expanded={open}
+      aria-controls={contentId}
+      aria-label={open ? `Collapse ${title}` : `Expand ${title}`}
+      on:click={toggle}
+    >
+      <span class="collapsible-section-heading">
+        <slot name="heading">{title}</slot>
+      </span>
+      <span
+        class="collapsible-section-indicator"
+        class:collapsible-section-indicator-open={open}
+        aria-hidden="true"
+      >
+        <ChevronDownIcon />
+      </span>
+    </button>
+    <slot name="actions" />
+  </div>
+
+  {#if open}
+    <div id={contentId} class="collapsible-section-content" aria-labelledby={labelledBy}>
+      <slot />
+    </div>
+  {/if}
+</div>
+
+<style>
+  .collapsible-section,
+  .collapsible-section-header {
+    box-sizing: border-box;
+    width: 100%;
+    min-width: 0;
+  }
+
+  .collapsible-section-header {
+    display: flex;
+    align-items: center;
+    gap: 0.25rem;
+  }
+
+  .collapsible-section-toggle {
+    -webkit-appearance: none;
+       -moz-appearance: none;
+            appearance: none;
+    display: flex;
+    align-items: center;
+    gap: 0.75rem;
+    flex: 1;
+    box-sizing: border-box;
+    width: 100%;
+    min-width: 0;
+    padding: 0.5rem;
+    border: 0;
+    border-radius: 0.375rem;
+    background: transparent;
+    color: inherit;
+    font: inherit;
+    font-weight: 600;
+    text-align: start;
+    cursor: pointer;
+  }
+
+  .collapsible-section-toggle:hover {
+    background: rgba(127, 127, 127, 0.08);
+  }
+
+  .collapsible-section-toggle:focus {
+    outline: none;
+  }
+
+  .collapsible-section-toggle:focus-visible {
+    outline: 2px solid Highlight;
+    outline-offset: 2px;
+  }
+
+  .collapsible-section-heading {
+    flex: 1;
+    min-width: 0;
+  }
+
+  .collapsible-section-indicator {
+    display: inline-flex;
+    flex: none;
+    transform: rotate(-90deg);
+    transition: transform 150ms ease;
+  }
+
+  .collapsible-section-indicator-open {
+    transform: rotate(0deg);
+  }
+
+  .collapsible-section-content {
+    display: flex;
+    flex-direction: column;
+    gap: 0.5rem;
+    box-sizing: border-box;
+    width: auto;
+    min-width: 0;
+    margin-top: 0.5rem;
+    margin-inline-start: 0.5rem;
+    padding-inline-start: 0.75rem;
+    /* border-inline-start: 2px solid rgba(127, 127, 127, 0.25); */
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .collapsible-section-indicator {
+      transition: none;
+    }
+  }
+</style>

package/dist/form-fields/CollapsibleSection.svelte.d.ts

@@ -0,0 +1,26 @@
+import { SvelteComponent } from "svelte";
+declare const __propDef: {
+    props: {
+        title: string;
+        open?: boolean;
+        contentId?: string | undefined;
+        labelledBy?: string | undefined;
+        onToggle?: ((open: boolean) => void) | undefined;
+    };
+    events: {
+        [evt: string]: CustomEvent<any>;
+    };
+    slots: {
+        heading: {};
+        actions: {};
+        default: {};
+    };
+    exports?: {} | undefined;
+    bindings?: string | undefined;
+};
+export type CollapsibleSectionProps = typeof __propDef.props;
+export type CollapsibleSectionEvents = typeof __propDef.events;
+export type CollapsibleSectionSlots = typeof __propDef.slots;
+export default class CollapsibleSection extends SvelteComponent<CollapsibleSectionProps, CollapsibleSectionEvents, CollapsibleSectionSlots> {
+}
+export {};

package/dist/form-fields/FieldLabel.svelte

@@ -1,12 +1,27 @@
-<script>import { Label } from "@stubber/ui/label";
+<script>import { getContext } from "svelte";
 import FieldExprToggle from "./FieldExprToggle.svelte";
+import { STYLES_CONTEXT, classNames } from "./styles";
 export let fieldStore;
+export let with_margin = true;
+const styles = getContext(STYLES_CONTEXT);
 $: hide_label = $fieldStore.hide_label;
 </script>
 
-<div class="mb-1 flex flex-row items-center justify-between">
+<div class="field-label-wrapper" class:field-label-wrapper-spacing={with_margin}>
   {#if !hide_label}
-    <Label for={$fieldStore.id}>{$fieldStore.label}</Label>
+    <label class={$styles.label} for={$fieldStore.id}>{$fieldStore.label}</label>
   {/if}
   <FieldExprToggle {fieldStore} />
 </div>
+
+<style>
+  .field-label-wrapper {
+    display: flex;
+    justify-content: space-between;
+    align-items: center;
+  }
+
+  .field-label-wrapper-spacing {
+    margin-bottom: 0.25rem;
+  }
+</style>

package/dist/form-fields/FieldLabel.svelte.d.ts

@@ -4,6 +4,7 @@ import type { IBuiltField } from "./interfaces";
 declare const __propDef: {
     props: {
         fieldStore: Writable<IBuiltField>;
+        with_margin?: boolean;
     };
     events: {
         [evt: string]: CustomEvent<any>;

package/dist/form-fields/FieldMessage.svelte

@@ -1,15 +1,26 @@
-<script>import { Label } from "@stubber/ui/label";
+<script>import { getContext } from "svelte";
+import { STYLES_CONTEXT, classNames } from "./styles";
 export let fieldStore;
+const styles = getContext(STYLES_CONTEXT);
 $: validation_result = $fieldStore.validation_result;
-$: type = validation_result?.type;
 </script>
 
-<Label
+<p
   id="message-{$fieldStore.id}"
-  for={$fieldStore.id}
-  class="block truncate text-xs {!$fieldStore.validation_result ? 'invisible' : ''} {type == 'error'
-    ? 'text-red-500'
-    : 'text-muted-foreground'}"
+  aria-hidden={!validation_result}
+  class={classNames("field-message", $styles.message)}
+  data-variant={validation_result?.type === "error" ? "error" : "help"}
 >
-  {$fieldStore.validation_result?.message}
-</Label>
+  {validation_result?.message ?? "\u00a0"}
+</p>
+
+<style>
+  .field-message {
+    margin: 0;
+    min-height: 1em;
+  }
+
+  .field-message[aria-hidden="true"] {
+    visibility: hidden;
+  }
+</style>

package/dist/form-fields/Form.svelte

@@ -1,6 +1,7 @@
-<script>import { setContext } from "svelte";
+<script>import { getContext, setContext } from "svelte";
 import { get as getStoreValue, writable } from "svelte/store";
 import FormField from "./form-field.svelte";
+import { STYLES_CONTEXT } from "./styles";
 import { build_fields } from "./utils";
 import { validate_field } from "./validations/validate_field";
 export let initial_form;
@@ -9,7 +10,14 @@ export let attachments = writable([]);
 export let dependencies = void 0;
 export let form_valid = false;
 export let dynamic_field_type = false;
+export let styles = void 0;
 setContext("dynamic_field_type", dynamic_field_type);
+const parentStyles = getContext(STYLES_CONTEXT);
+const stylesContext = writable(
+  styles ?? (parentStyles ? getStoreValue(parentStyles) : {})
+);
+setContext(STYLES_CONTEXT, stylesContext);
+$: stylesContext.set(styles ?? (parentStyles ? getStoreValue(parentStyles) : {}));
 let fields = [];
 let form_errors = {};
 const rebuild_fields = (initial_form2, form2) => {
@@ -42,8 +50,17 @@ const validate_form = async (_) => {
 };
 </script>
 
-<div class="flex flex-col gap-y-2">
+<div class="form">
   {#each fields as fieldStore (getStoreValue(fieldStore).id)}
     <FormField {fieldStore} />
   {/each}
 </div>
+
+<style>
+  .form {
+    display: flex;
+    flex-direction: column;
+    gap: 0.5rem;
+    width: 100%;
+  }
+</style>