npm - @joyautomation/salt - Versions diffs - 0.1.0 → 0.1.2 - Mend

@joyautomation/salt 0.1.0 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (63) hide show

package/README.md CHANGED Viewed

@@ -1,58 +1,361 @@
-# create-svelte
+# @joyautomation/salt
-Everything you need to build a Svelte library, powered by [`create-svelte`](https://github.com/sveltejs/kit/tree/main/packages/create-svelte).
+A Svelte 5 component library with theming, forms, icons, and notifications.
-Read more about creating a library [in the docs](https://kit.svelte.dev/docs/packaging).
+## Installation
-## Creating a project
+```bash
+pnpm add @joyautomation/salt
+```
-If you're seeing this, you've probably already done this step. Congrats!
+Import the styles in your root layout or app entry point:
-```bash
-# create a new project in the current directory
-npm create svelte@latest
+```svelte
+<script>
+  import '@joyautomation/salt/styles.scss'
+</script>
+```
+## Theming
+Salt includes a light/dark theme system using CSS custom variables. Apply the default theme class to `<body>` in your `app.html`:
-# create a new project in my-app
-npm create svelte@latest my-app
+```html
+<body class="themeLight" data-sveltekit-preload-data="hover">
+  %sveltekit.body%
+</body>
 ```
-## Developing
+### ThemeButton
-Once you've created a project and installed dependencies with `npm install` (or `pnpm install` or `yarn`), start a development server:
+A toggle button that switches between light and dark mode via a SvelteKit form action.
-```bash
-npm run dev
+```svelte
+<script>
+  import { ThemeButton } from '@joyautomation/salt'
+</script>
-# or start the server and open the app in a new browser tab
-npm run dev -- --open
+<ThemeButton theme="themeLight" />
 ```
-Everything inside `src/lib` is part of your library, everything inside `src/routes` can be used as a showcase or preview app.
+Wire up the server action in your `+layout.server.ts`:
-## Building
+```ts
+import { actions as saltActions } from '@joyautomation/salt'
+import type { Actions } from '@sveltejs/kit'
-To build your library:
+export const actions: Actions = {
+  setTheme: saltActions.setTheme
+}
+```
-```bash
-npm run package
+### ThemeSwitch
+A three-option selector (System / Light / Dark):
+```svelte
+<script>
+  import { ThemeSwitch } from '@joyautomation/salt'
+</script>
+<ThemeSwitch />
+```
+### Theme State
+Programmatic access to the current theme:
+```ts
+import { themeState, getEffectiveTheme } from '@joyautomation/salt'
+// Read current theme
+themeState.value // 'themeSystem' | 'themeLight' | 'themeDark'
+// Get resolved theme (resolves 'themeSystem' to actual preference)
+getEffectiveTheme() // 'themeLight' | 'themeDark'
+// Set theme programmatically
+themeState.set('themeDark')
+// Initialize from server cookie
+themeState.initialize(serverTheme)
+```
+## Toast Notifications
+Drop-in toast notification system that auto-displays messages returned from SvelteKit form actions.
+### Setup
+Add the `Toast` component to your root layout:
+```svelte
+<script>
+  import { Toast } from '@joyautomation/salt'
+</script>
+<slot />
+<Toast />
+```
+### Triggering Toasts from Form Actions
+Return an object with `message` and `type` from any form action:
+```ts
+// +page.server.ts
+export const actions = {
+  save: async () => {
+    return {
+      message: 'Changes saved successfully',
+      type: 'success' // 'success' | 'error' | 'warning'
+    }
+  }
+}
+```
+### Triggering Toasts Programmatically
+```ts
+import { state } from '@joyautomation/salt'
+state.addNotification({
+  message: 'Something happened',
+  type: 'warning'
+})
+```
+Notifications auto-dismiss after 5 seconds.
+## Forms
+A JSON-driven form system using a 2D array layout where each inner array represents a row of fields.
+### Basic Usage
+```svelte
+<script>
+  import { forms } from '@joyautomation/salt'
+  import type { FormInputs } from '@joyautomation/salt'
+  const inputs: FormInputs = $state([
+    // Row 1: two fields side by side
+    [
+      {
+        id: 'name',
+        name: 'name',
+        label: 'Name',
+        type: 'text',
+        value: '',
+        validations: [[(v) => v.trim().length === 0, 'Name is required']]
+      },
+      {
+        id: 'email',
+        name: 'email',
+        label: 'Email',
+        type: 'email',
+        value: '',
+        validations: [
+          [(v) => v.trim().length === 0, 'Email is required'],
+          [(v) => !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(v), 'Enter a valid email']
+        ]
+      }
+    ],
+    // Row 2: select dropdown
+    [
+      {
+        id: 'role',
+        name: 'role',
+        label: 'Role',
+        type: 'select',
+        value: 'user',
+        validations: [],
+        options: [
+          { value: 'user', label: 'User' },
+          { value: 'admin', label: 'Admin' }
+        ]
+      }
+    ],
+    // Row 3: textarea
+    [
+      {
+        id: 'notes',
+        name: 'notes',
+        label: 'Notes',
+        type: 'textarea',
+        value: '',
+        validations: []
+      }
+    ]
+  ])
+</script>
+<forms.Form inputs={inputs} action="?/save" buttonText="Save" />
 ```
-To create a production version of your showcase app:
+### Field Types
+Set `type` on an `InputProps` entry:
+- **Text inputs**: `text`, `password`, `email`, `number`, `tel`, `datetime-local`, etc.
+- **Textarea**: `textarea` — renders a resizable text area
+- **Select**: `select` — renders a dropdown, requires `options: { value: string, label: string }[]`
+### Validation
+Each field has a `validations` array of `[testFn, errorMessage]` tuples. The test function returns `true` when the value is **invalid**:
+```ts
+validations: [
+  [(value) => value.length === 0, 'Required'],
+  [(value) => value.length < 3, 'Must be at least 3 characters'],
+  // Cross-field validation — second param gives access to all form inputs
+  [(value, inputs) => {
+    const other = inputs.flat().find(i => i.name === 'password')
+    return value !== other?.value
+  }, 'Passwords must match']
+]
+```
+The submit button is disabled until all validations pass.
+### Form Component
+```svelte
+<forms.Form
+  inputs={formInputs}
+  action="?/submit"
+  buttonText="Submit"
+  onsubmitstart={() => console.log('submitting...')}
+  onsubmitend={() => console.log('done')}
+/>
+```
+Props:
+- `inputs` — `FormInputs` (2D array of `InputProps`)
+- `action` — SvelteKit form action path
+- `buttonText` — submit button label (default: `'Submit'`)
+- `onsubmitstart` / `onsubmitend` — optional callbacks
+### Individual Components
+You can also use form components standalone:
+```svelte
+<forms.Input
+  id="name"
+  name="name"
+  label="Name"
+  type="text"
+  bind:value={name}
+  validations={[[(v) => v.length === 0, 'Required']]}
+  touched={true}
+/>
+<forms.Select
+  id="color"
+  name="color"
+  label="Color"
+  bind:value={color}
+  validations={[]}
+  options={[{ value: 'red', label: 'Red' }, { value: 'blue', label: 'Blue' }]}
+/>
+```
+### SearchableSelect
+A filterable dropdown with keyboard navigation, independent of the form system:
+```svelte
+<script>
+  import { forms } from '@joyautomation/salt'
+  let selected = $state('')
+</script>
+<forms.SearchableSelect
+  options={[
+    { value: 'svelte', label: 'Svelte', sublabel: 'Cybernetically enhanced' },
+    { value: 'react', label: 'React', sublabel: 'A JavaScript library' }
+  ]}
+  placeholder="Choose a framework..."
+  onSelect={(option) => (selected = option.value)}
+  disabled={false}
+/>
+```
+### Types
+```ts
+import type { InputProps, FormInputs, FormInputsPartial } from '@joyautomation/salt'
+// InputProps — single field configuration
+// FormInputs — InputProps[][] (2D array, each inner array is a row)
+// FormInputsPartial — partial version for merging/patching field configs
+```
+## Icons
+All 648 [Heroicons](https://heroicons.com) (324 outline + 324 solid) are available as tree-shakeable Svelte components.
+### Usage
+```svelte
+<script>
+  // Outline icons (default export)
+  import { AcademicCap, ArrowPath, Trash } from '@joyautomation/salt/icons'
+  // Style-specific imports
+  import { AcademicCap } from '@joyautomation/salt/icons/outline'
+  import { AcademicCap } from '@joyautomation/salt/icons/solid'
+</script>
+<!-- Default size is 1.5rem -->
+<AcademicCap />
+<!-- Custom size -->
+<ArrowPath size="2rem" />
+<Trash size="1rem" />
+```
+Icons inherit `currentColor` so they match the surrounding text color.
+### Regenerating Icons
+If you update the SVGs in `src/lib/components/icons/svg/`, regenerate with:
 ```bash
-npm run build
+npm run generate:icons
 ```
-You can preview the production build with `npm run preview`.
+## Toggle
-> To deploy your app, you may need to install an [adapter](https://kit.svelte.dev/docs/adapters) for your target environment.
+A toggle switch component with hidden form input:
-## Publishing
+```svelte
+<script>
+  import { Toggle } from '@joyautomation/salt'
+</script>
-Go into the `package.json` and give your package the desired name through the `"name"` option. Also consider adding a `"license"` field and point it to a `LICENSE` file which you can create from a template (one popular option is the [MIT license](https://opensource.org/license/mit/)).
+<Toggle id="notifications" name="notifications" checked={true} />
+```
+Props:
+- `id` — input ID
+- `name` — form field name
+- `checked` — boolean state
+- `buttonType` — `'button'` (default) or `'submit'`
+- `selector` / `selectorName` — optional additional hidden input
-To publish your library to [npm](https://www.npmjs.com):
+## Development
 ```bash
-npm publish
+pnpm install
+pnpm dev          # starts dev server on port 3014
+pnpm run check    # type check
+pnpm run package  # build the library
 ```
+## Publishing
+Create a [GitHub release](https://github.com/joyautomation/salt/releases) with a tag like `v0.2.0`. The CI workflow will automatically set the version, build, and publish to npm.

package/dist/components/forms/Form.svelte CHANGED Viewed

@@ -1,9 +1,9 @@
 <script lang="ts">
-	import { enhance } from '$app/forms';
-	import Input from './Input.svelte';
-	import Select from './Select.svelte';
-	import type { FormInputs } from './types.js';
-	import { slide } from 'svelte/transition';
+	import { enhance } from '$app/forms'
+	import Input from './Input.svelte'
+	import Select from './Select.svelte'
+	import type { FormInputs } from './types.js'
+	import { slide } from 'svelte/transition'
 	const {
 		inputs: propInputs,
@@ -12,29 +12,29 @@
 		onsubmitstart,
 		onsubmitend
 	}: {
-		inputs: FormInputs;
-		action: string;
-		buttonText?: string;
-		onsubmitstart?: () => void;
-		onsubmitend?: () => void;
-	} = $props();
+		inputs: FormInputs
+		action: string
+		buttonText?: string
+		onsubmitstart?: () => void
+		onsubmitend?: () => void
+	} = $props()
-	let inputs = $state(propInputs);
-	let submitting = $state(false);
+	let inputs = $state(propInputs)
+	let submitting = $state(false)
 	$effect(() => {
-		inputs = propInputs;
-	});
+		inputs = propInputs
+	})
 	const valid = $derived(
 		inputs.every((row) =>
 			row.every((input) => {
-				return input.validations.every(([validation, _message]) => {
-					return !validation(input.value, inputs);
-				});
+				return input.validations.every(([validation]) => {
+					return !validation(input.value, inputs)
+				})
 			})
 		)
-	);
+	)
 </script>
 <form
@@ -42,13 +42,13 @@
 	method="post"
 	{action}
 	use:enhance={() => {
-		submitting = true;
-		onsubmitstart?.();
+		submitting = true
+		onsubmitstart?.()
 		return async ({ update }) => {
-			submitting = false;
-			onsubmitend?.();
-			update({ reset: false });
-		};
+			submitting = false
+			onsubmitend?.()
+			update({ reset: false })
+		}
 	}}
 >
 	{#each inputs as row}

package/dist/components/forms/Input.svelte CHANGED Viewed

@@ -1,6 +1,6 @@
 <script lang="ts">
-	import { slide } from 'svelte/transition';
-	import type { FormInputs, InputProps } from './types.js';
+	import { slide } from 'svelte/transition'
+	import type { FormInputs, InputProps } from './types.js'
 	let {
 		id,
@@ -13,12 +13,12 @@
 		inputs,
 		touched = false,
 		onblur = () => {}
-	}: InputProps & { inputs?: FormInputs; touched?: boolean; onblur?: () => void } = $props();
+	}: InputProps & { inputs?: FormInputs; touched?: boolean; onblur?: () => void } = $props()
 	const validationResult = $derived(
-		validations.find(([validation, _message]) => {
-			return validation(value, inputs ?? []);
+		validations.find(([validation]) => {
+			return validation(value, inputs ?? [])
 		})?.[1] || null
-	);
+	)
 </script>
 <div class="input" class:input--invalid={touched && validationResult != null}>

package/dist/components/forms/SearchableSelect.svelte CHANGED Viewed

@@ -1,121 +1,121 @@
 <script lang="ts">
-	import ChevronDown from '../icons/outline/ChevronDown.svelte';
+	import ChevronDown from '../icons/outline/ChevronDown.svelte'
 	type Option = {
-		value: string;
-		label: string;
-		sublabel?: string;
-	};
+		value: string
+		label: string
+		sublabel?: string
+	}
 	type Props = {
-		options: Option[];
-		placeholder?: string;
-		onSelect: (option: Option) => void;
-		disabled?: boolean;
-	};
+		options: Option[]
+		placeholder?: string
+		onSelect: (option: Option) => void
+		disabled?: boolean
+	}
-	let { options, placeholder = 'Select...', onSelect, disabled = false }: Props = $props();
+	let { options, placeholder = 'Select...', onSelect, disabled = false }: Props = $props()
-	let isOpen = $state(false);
-	let searchQuery = $state('');
-	let highlightedIndex = $state(-1);
-	let inputRef: HTMLInputElement | undefined = $state();
-	let dropdownRef: HTMLDivElement | undefined = $state();
+	let isOpen = $state(false)
+	let searchQuery = $state('')
+	let highlightedIndex = $state(-1)
+	let inputRef: HTMLInputElement | undefined = $state()
+	let dropdownRef: HTMLDivElement | undefined = $state()
 	let filteredOptions = $derived(
 		searchQuery.trim() === ''
 			? options
 			: options.filter((opt) => {
-					const query = searchQuery.toLowerCase();
+					const query = searchQuery.toLowerCase()
 					return (
 						opt.label.toLowerCase().includes(query) ||
 						(opt.sublabel && opt.sublabel.toLowerCase().includes(query))
-					);
+					)
 				})
-	);
+	)
 	function openDropdown() {
-		if (disabled) return;
-		isOpen = true;
-		highlightedIndex = -1;
-		setTimeout(() => inputRef?.focus(), 0);
+		if (disabled) return
+		isOpen = true
+		highlightedIndex = -1
+		setTimeout(() => inputRef?.focus(), 0)
 	}
 	function closeDropdown() {
-		isOpen = false;
-		searchQuery = '';
-		highlightedIndex = -1;
+		isOpen = false
+		searchQuery = ''
+		highlightedIndex = -1
 	}
 	function selectOption(option: Option) {
-		onSelect(option);
-		closeDropdown();
+		onSelect(option)
+		closeDropdown()
 	}
 	function handleKeydown(e: KeyboardEvent) {
 		if (!isOpen) {
 			if (e.key === 'Enter' || e.key === ' ' || e.key === 'ArrowDown') {
-				e.preventDefault();
-				openDropdown();
+				e.preventDefault()
+				openDropdown()
 			}
-			return;
+			return
 		}
 		switch (e.key) {
 			case 'ArrowDown':
-				e.preventDefault();
-				highlightedIndex = Math.min(highlightedIndex + 1, filteredOptions.length - 1);
-				scrollToHighlighted();
-				break;
+				e.preventDefault()
+				highlightedIndex = Math.min(highlightedIndex + 1, filteredOptions.length - 1)
+				scrollToHighlighted()
+				break
 			case 'ArrowUp':
-				e.preventDefault();
-				highlightedIndex = Math.max(highlightedIndex - 1, 0);
-				scrollToHighlighted();
-				break;
+				e.preventDefault()
+				highlightedIndex = Math.max(highlightedIndex - 1, 0)
+				scrollToHighlighted()
+				break
 			case 'Enter':
-				e.preventDefault();
+				e.preventDefault()
 				if (highlightedIndex >= 0 && highlightedIndex < filteredOptions.length) {
-					selectOption(filteredOptions[highlightedIndex]);
+					selectOption(filteredOptions[highlightedIndex])
 				}
-				break;
+				break
 			case 'Escape':
-				e.preventDefault();
-				closeDropdown();
-				break;
+				e.preventDefault()
+				closeDropdown()
+				break
 			case 'Tab':
-				closeDropdown();
-				break;
+				closeDropdown()
+				break
 		}
 	}
 	function scrollToHighlighted() {
-		if (!dropdownRef || highlightedIndex < 0) return;
-		const items = dropdownRef.querySelectorAll('.searchable-select__option');
-		const item = items[highlightedIndex] as HTMLElement;
+		if (!dropdownRef || highlightedIndex < 0) return
+		const items = dropdownRef.querySelectorAll('.searchable-select__option')
+		const item = items[highlightedIndex] as HTMLElement
 		if (item) {
-			item.scrollIntoView({ block: 'nearest' });
+			item.scrollIntoView({ block: 'nearest' })
 		}
 	}
 	function handleClickOutside(e: MouseEvent) {
-		const target = e.target as Node;
+		const target = e.target as Node
 		if (dropdownRef && !dropdownRef.contains(target)) {
-			closeDropdown();
+			closeDropdown()
 		}
 	}
 	$effect(() => {
 		if (isOpen) {
-			document.addEventListener('click', handleClickOutside, true);
-			return () => document.removeEventListener('click', handleClickOutside, true);
+			document.addEventListener('click', handleClickOutside, true)
+			return () => document.removeEventListener('click', handleClickOutside, true)
 		}
-	});
+	})
 	$effect(() => {
 		if (searchQuery) {
-			highlightedIndex = filteredOptions.length > 0 ? 0 : -1;
+			highlightedIndex = filteredOptions.length > 0 ? 0 : -1
 		}
-	});
+	})
 </script>
 <div class="searchable-select" class:searchable-select--disabled={disabled}>