npm - @joyautomation/salt - Versions diffs - 0.0.29 → 0.1.1 - Mend

@joyautomation/salt 0.0.29 → 0.1.1

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 (1361) 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/ThemeButton.svelte CHANGED Viewed

@@ -1,7 +1,7 @@
 <script lang="ts">
   import { enhance } from '$app/forms'
-  import Moon from './icons/Moon.svelte'
-  import Sun from './icons/Sun.svelte'
+  import Moon from './icons/outline/Moon.svelte'
+  import Sun from './icons/outline/Sun.svelte'
   export let theme: string
   export let action = 'setTheme'
 </script>

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

@@ -0,0 +1,111 @@
+<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'
+	const {
+		inputs: propInputs,
+		action,
+		buttonText = 'Submit',
+		onsubmitstart,
+		onsubmitend
+	}: {
+		inputs: FormInputs
+		action: string
+		buttonText?: string
+		onsubmitstart?: () => void
+		onsubmitend?: () => void
+	} = $props()
+	let inputs = $state(propInputs)
+	let submitting = $state(false)
+	$effect(() => {
+		inputs = propInputs
+	})
+	const valid = $derived(
+		inputs.every((row) =>
+			row.every((input) => {
+				return input.validations.every(([validation]) => {
+					return !validation(input.value, inputs)
+				})
+			})
+		)
+	)
+</script>
+<form
+	class="form space-y-1"
+	method="post"
+	{action}
+	use:enhance={() => {
+		submitting = true
+		onsubmitstart?.()
+		return async ({ update }) => {
+			submitting = false
+			onsubmitend?.()
+			update({ reset: false })
+		}
+	}}
+>
+	{#each inputs as row}
+		<div class="form__row">
+			{#each row as input}
+				<div>
+					{#if input.type === 'select'}
+						<Select {...input} bind:value={input.value} {inputs} options={input.options || []} />
+					{:else}
+						<Input {...input} bind:value={input.value} {inputs} />
+					{/if}
+				</div>
+			{/each}
+		</div>
+	{/each}
+	<button class="button--primary" disabled={!valid || submitting}>
+		{#if submitting}
+			<div class="form__spinner-container" transition:slide>
+				<span class="form__spinner"></span>
+			</div>
+		{:else}
+			<div transition:slide>
+				{buttonText}
+			</div>
+		{/if}
+	</button>
+</form>
+<style>.form {
+  display: flex;
+  flex-direction: column;
+}
+.form > .form__row {
+  display: flex;
+}
+.form > .form__row > * {
+  flex-grow: 1;
+}
+.form__spinner-container {
+  display: flex;
+  justify-content: center;
+  align-items: center;
+}
+.form__spinner {
+  display: inline-block;
+  width: 16px;
+  height: 16px;
+  border: 2px solid var(--theme-neutral-300);
+  border-top-color: var(--white, #fff);
+  border-radius: 50%;
+  animation: spin 0.6s linear infinite;
+}
+@keyframes spin {
+  to {
+    transform: rotate(360deg);
+  }
+}</style>

package/dist/components/forms/Form.svelte.d.ts ADDED Viewed

@@ -0,0 +1,11 @@
+import type { FormInputs } from './types.js';
+type $$ComponentProps = {
+    inputs: FormInputs;
+    action: string;
+    buttonText?: string;
+    onsubmitstart?: () => void;
+    onsubmitend?: () => void;
+};
+declare const Form: import("svelte").Component<$$ComponentProps, {}, "">;
+type Form = ReturnType<typeof Form>;
+export default Form;

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

@@ -1,20 +1,77 @@
 <script lang="ts">
-	import type { InputProps } from './types.js'
+	import { slide } from 'svelte/transition'
+	import type { FormInputs, InputProps } from './types.js'
-	const { id, name, label, type, value, validation }: InputProps = $props()
-	const validationResult = $derived(validation(value))
+	let {
+		id,
+		name,
+		label,
+		type,
+		step,
+		value = $bindable(''),
+		validations,
+		inputs,
+		touched = false,
+		onblur = () => {}
+	}: InputProps & { inputs?: FormInputs; touched?: boolean; onblur?: () => void } = $props()
+	const validationResult = $derived(
+		validations.find(([validation]) => {
+			return validation(value, inputs ?? [])
+		})?.[1] || null
+	)
 </script>
-<div class="input">
-	<label for={id}>{label}</label>
-	<input {id} {name} {type} />
-	{#if validationResult != null}<div class="input__validation">{validationResult}</div>{/if}
+<div class="input" class:input--invalid={touched && validationResult != null}>
+	{#if label != null}
+		<label for={id}>{label}</label>
+	{/if}
+	{#if type === 'textarea'}
+		<textarea {id} {name} bind:value {onblur}></textarea>
+	{:else}
+		<input {id} {name} {step} {type} bind:value {onblur} />
+	{/if}
+	{#if touched && validationResult != null}<div transition:slide class="input__validation">
+			{validationResult}
+		</div>{/if}
 </div>
 <style>.input {
   display: flex;
   flex-direction: column;
 }
+.input > .input__validation {
+  color: var(--theme-error-400, var(--red-400));
+  font-size: var(--text-xs);
+  line-height: var(--text-xs-lh);
+}
+.input > label {
+  color: var(--theme-text);
+  font-family: var(--theme-font-basic, inherit);
+  font-size: var(--text-sm);
+  line-height: var(--text-sm-lh);
+  text-transform: capitalize;
+}
 .input > * {
   margin-top: var(--spacing-unit);
+}
+.input > input, .input > textarea {
+  background-color: var(--theme-neutral-200);
+  border: solid 1px var(--theme-neutral-300);
+  color: var(--theme-text);
+  padding: calc(var(--spacing-unit) * 1.5) calc(var(--spacing-unit) * 2);
+  border-radius: var(--rounded-sm);
+  font-size: var(--text-base);
+}
+.input > input:focus, .input > textarea:focus {
+  outline: none;
+  border-color: var(--theme-primary);
+}
+.input > textarea {
+  resize: vertical;
+  min-height: 100px;
+  font-family: inherit;
+}
+.input--invalid > input, .input--invalid > textarea {
+  border: solid 1px var(--theme-error-400, var(--red-400));
 }</style>

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

@@ -1,4 +1,9 @@
-import type { InputProps } from './types.js';
-declare const Input: import("svelte").Component<InputProps, {}, "">;
+import type { FormInputs, InputProps } from './types.js';
+type $$ComponentProps = InputProps & {
+    inputs?: FormInputs;
+    touched?: boolean;
+    onblur?: () => void;
+};
+declare const Input: import("svelte").Component<$$ComponentProps, {}, "value">;
 type Input = ReturnType<typeof Input>;
 export default Input;