@marianmeres/stuic 3.66.1 → 3.68.0

package/dist/components/CommandMenu/CommandMenu.svelte

@@ -58,6 +58,8 @@
 		classOption?: string;
 		classOptionActive?: string;
 		showAllOnEmptyQ?: boolean;
+		/** Skip stuic base classes (user provides their own styling) */
+		unstyled?: boolean;
 	}
 </script>
 
@@ -81,6 +83,7 @@
 		itemIdPropName = "id",
 		searchPlaceholder,
 		showAllOnEmptyQ,
+		unstyled = false,
 	}: Props = $props();
 
 	function _renderOptionLabel(item: Item): string {
@@ -138,10 +141,16 @@
 				_optionsColl.clear().addMany(res);
 			})
 			.catch((e) => {
+				// Surface errors only for the latest in-flight request
+				if (currentRequest !== fetchRequestId) return;
 				console.error(e);
 				notifications?.error(`${e}`);
 			})
-			.finally(() => (isFetching = false));
+			.finally(() => {
+				// Only the latest request toggles the fetching state back off
+				// so the spinner doesn't flicker when a stale response arrives late.
+				if (currentRequest === fetchRequestId) isFetching = false;
+			});
 	});
 
 	//
@@ -263,14 +272,20 @@
 			>
 				{#snippet inputBefore()}
 					<div
-						class="flex flex-col items-center justify-center pl-3 stuic-command-menu-muted"
+						class={twMerge(
+							"flex flex-col items-center justify-center pl-3",
+							!unstyled && "stuic-command-menu-muted"
+						)}
 					>
 						{@html iconSearch({ size: 19 })}
 					</div>
 				{/snippet}
 				{#snippet inputAfter()}
 					<div
-						class="flex pl-2 items-center justify-center stuic-command-menu-placeholder"
+						class={twMerge(
+							"flex pl-2 items-center justify-center",
+							!unstyled && "stuic-command-menu-placeholder"
+						)}
 					>
 						{#if isFetching}
 							<Spinner class="w-4" />
@@ -302,7 +317,7 @@
 					{#if options.size}
 						<div
 							class={twMerge(
-								"stuic-command-menu-options",
+								!unstyled && "stuic-command-menu-options",
 								"block space-y-1 p-1",
 								"overflow-y-auto overflow-x-hidden mb-1",
 								"border-t"
@@ -314,11 +329,13 @@
 							aria-label="Search results"
 						>
 							{#each _normalize_and_group_options(options.items) as [_optgroup, _opts]}
-								<!-- {console.log(11111, _optgroup, _opts)} -->
 								<div class="p-1">
 									{#if _optgroup}
 										<div
-											class="stuic-command-menu-group-header mb-1 p-1 font-semibold uppercase tracking-wide"
+											class={twMerge(
+												"mb-1 p-1 font-semibold uppercase tracking-wide",
+												!unstyled && "stuic-command-menu-group-header"
+											)}
 										>
 											{_optgroup}
 										</div>
@@ -327,7 +344,6 @@
 										{#each _opts as item (item[itemIdPropName])}
 											{@const active =
 												item[itemIdPropName] === options.active?.[itemIdPropName]}
-											<!-- {@const isSelected = false} -->
 											<li class:active role="presentation">
 												<ListItemButton
 													id={btn_id(item[itemIdPropName])}

package/dist/components/CommandMenu/CommandMenu.svelte.d.ts

@@ -16,6 +16,8 @@ export interface Props {
     classOption?: string;
     classOptionActive?: string;
     showAllOnEmptyQ?: boolean;
+    /** Skip stuic base classes (user provides their own styling) */
+    unstyled?: boolean;
 }
 declare const CommandMenu: import("svelte").Component<Props, {
     close: () => void;

package/dist/components/CronInput/CronInput.svelte

@@ -17,6 +17,8 @@
 		value?: string;
 		el?: HTMLElement;
 		id?: string;
+		/** Opt out of stuic base classes for full styling control */
+		unstyled?: boolean;
 
 		// Mode toggle (overrides show* flags when defined)
 		mode?: CronInputMode;
@@ -185,6 +187,7 @@
 		value = $bindable("* * * * *"),
 		el = $bindable(),
 		id = getId(),
+		unstyled = false,
 		//
 		mode = $bindable<CronInputMode | undefined>("predefined"),
 		//
@@ -435,14 +438,21 @@
 	>
 		<div class="w-full flex">
 			<div
-				class={twMerge("stuic-cron-input-content", error && "has-error")}
+				class={unstyled
+					? error
+						? "has-error"
+						: undefined
+					: twMerge("stuic-cron-input-content", error && "has-error")}
 				data-presets-only={presetsOnly ? "" : undefined}
 			>
 				{#if _showPresets}
 					<select
-						class={twMerge("stuic-cron-input-preset", classPreset)}
+						class={unstyled
+							? classPreset
+							: twMerge("stuic-cron-input-preset", classPreset)}
 						bind:value={selectedPreset}
 						onchange={onPresetChange}
+						aria-label="Cron schedule preset"
 						{disabled}
 					>
 						<option value="">Custom</option>
@@ -453,18 +463,33 @@
 				{/if}
 
 				{#if _showFields}
-				<div class={twMerge("stuic-cron-input-fields", classFields)}>
+				<div
+					class={unstyled
+						? classFields
+						: twMerge("stuic-cron-input-fields", classFields)}
+				>
 					{#each FIELD_DEFS as def}
-						<div class={twMerge("stuic-cron-input-field", classField)}>
-							<span class={twMerge("stuic-cron-input-field-label", classFieldLabel)}>
+						<div
+							class={unstyled
+								? classField
+								: twMerge("stuic-cron-input-field", classField)}
+						>
+							<span
+								class={unstyled
+									? classFieldLabel
+									: twMerge("stuic-cron-input-field-label", classFieldLabel)}
+							>
 								{def.label}
 							</span>
 							<input
 								type="text"
-								class={twMerge("stuic-cron-input-field-input", classFieldInput)}
+								class={unstyled
+									? classFieldInput
+									: twMerge("stuic-cron-input-field-input", classFieldInput)}
 								bind:value={fields[def.key]}
 								oninput={onFieldInput}
 								placeholder={def.placeholder}
+								aria-label={`${def.label} (${def.placeholder})`}
 								{disabled}
 								autocomplete="off"
 								spellcheck={false}
@@ -477,10 +502,13 @@
 				{#if _showRawInput}
 					<input
 						type="text"
-						class={twMerge("stuic-cron-input-raw", classRaw)}
+						class={unstyled
+							? classRaw
+							: twMerge("stuic-cron-input-raw", classRaw)}
 						bind:value={rawValue}
 						oninput={onRawInput}
 						placeholder="* * * * *"
+						aria-label="Raw cron expression"
 						{disabled}
 						autocomplete="off"
 						spellcheck={false}
@@ -488,7 +516,11 @@
 				{/if}
 
 				{#if (_showDescription || _showNextRun) && humanDescription}
-					<div class={twMerge("stuic-cron-input-summary", classSummary)}>
+					<div
+						class={unstyled
+							? classSummary
+							: twMerge("stuic-cron-input-summary", classSummary)}
+					>
 						{humanDescription}
 					</div>
 				{/if}
@@ -497,8 +529,11 @@
 			{#if hasModeToggle}
 				<button
 					type="button"
-					class={twMerge(BTN_CLS, classToggleButton)}
+					class={unstyled
+						? classToggleButton
+						: twMerge(BTN_CLS, classToggleButton)}
 					onclick={toggleMode}
+					aria-label={mode === "predefined" ? "Switch to manual input" : "Switch to presets"}
 					{disabled}
 					use:tooltip={() => ({
 						enabled: true,

package/dist/components/CronInput/CronInput.svelte.d.ts

@@ -13,6 +13,8 @@ export interface Props {
     value?: string;
     el?: HTMLElement;
     id?: string;
+    /** Opt out of stuic base classes for full styling control */
+    unstyled?: boolean;
     mode?: CronInputMode;
     label?: SnippetWithId | THC;
     description?: SnippetWithId | THC;

package/dist/components/CronInput/README.md

@@ -0,0 +1,145 @@
+# CronInput
+
+A cron-expression editor with three progressive surfaces: **preset picker**, **5-field visual editor**, and **raw expression input** — plus a human-readable summary and the next-run preview. Backed by [`@marianmeres/cron`](https://www.npmjs.com/package/@marianmeres/cron).
+
+The cron expression string is the single source of truth; field / preset / raw surfaces are all views over it. All three stay in sync automatically when the bound `value` changes.
+
+## Usage
+
+### Basic (preset picker + manual editor toggle)
+
+```svelte
+<script lang="ts">
+    import { CronInput } from "@marianmeres/stuic";
+
+    let expression = $state("0 9 * * 1-5");
+</script>
+
+<CronInput bind:value={expression} label="Schedule" />
+```
+
+Default `mode` is `"predefined"` — users see the preset picker with a toggle button to flip into `"manual"` (5 fields + raw + summary). Setting `mode={undefined}` removes the toggle and shows all surfaces that the `show*` flags enable.
+
+### Flat layout (no toggle, explicit surfaces)
+
+```svelte
+<CronInput
+    bind:value={expression}
+    mode={undefined}
+    showPresets
+    showFields
+    showRawInput
+    showDescription
+    showNextRun
+/>
+```
+
+### Custom presets
+
+```svelte
+<script lang="ts">
+    import { CronInput, type CronPreset } from "@marianmeres/stuic";
+
+    const presets: CronPreset[] = [
+        { label: "Top of every hour", value: "0 * * * *" },
+        { label: "Daily at 09:00", value: "0 9 * * *" },
+        { label: "Every 5 minutes", value: "*/5 * * * *" },
+    ];
+</script>
+
+<CronInput bind:value={expression} {presets} />
+```
+
+### Watching next-run externally
+
+For places outside the CronInput that need the next-fire time (e.g. a dashboard card), use the exported `CronNextRun` helper:
+
+```svelte
+<script lang="ts">
+    import { CronNextRun } from "@marianmeres/stuic";
+    import { onDestroy } from "svelte";
+
+    const nr = new CronNextRun("0 9 * * 1-5");
+    onDestroy(() => nr.destroy());
+</script>
+
+<p>Next run: {nr.nextRunFormatted}</p>
+```
+
+> ⚠️ `CronNextRun` starts a 60-second interval in its constructor. **Always call `destroy()` on teardown**, or it will leak timers for the lifetime of the page.
+
+## Modes
+
+The `mode` prop controls which surfaces are visible and whether the toggle button is shown:
+
+| `mode`              | Toggle shown | Visible surfaces                                     |
+| ------------------- | ------------ | ---------------------------------------------------- |
+| `"predefined"`      | yes          | preset picker                                        |
+| `"manual"`          | yes          | fields + raw + description + next-run                |
+| `undefined`         | no           | whatever the `show*` flags enable (full control)     |
+
+When `mode` is defined, it **overrides** the individual `show*` flags. Set `mode={undefined}` if you want to pick surfaces yourself.
+
+## Expression ↔ fields sync
+
+The `value` string is canonical. Internally:
+
+- User edits a field → fields are composed back into an expression; `value` is set only if the result validates.
+- User edits the raw input → fields are re-derived from it; invalid input surfaces as a validation message.
+- User picks a preset → `value` is set directly.
+- External `value` change → fields & raw mirror it (unless the change came from this component in the same tick).
+
+Off-by-one conventions match standard cron:
+
+| Field        | Range  | Notes                                |
+| ------------ | ------ | ------------------------------------ |
+| minute       | 0-59   |                                      |
+| hour         | 0-23   |                                      |
+| day of month | 1-31   |                                      |
+| month        | 1-12   | 1 = January                          |
+| day of week  | 0-6    | 0 = Sunday                           |
+
+## Validation
+
+The component uses `new CronParser(value)` to validate. When invalid:
+
+- The visual invalid state comes from `InputWrap`'s standard validation wrapper (the same mechanism used by every `Field*` component — override via `classInputBoxWrapInvalid`).
+- The content div gets a `has-error` class hook you can target with your own CSS. No built-in style is applied to it — it's purely an extension point.
+- The `validate` prop (same shape as `FieldInput`'s) is supported; the component reports the parser's error message through the usual validation channel.
+
+## Timezone
+
+All next-run calculations use the **host's local timezone**. There is no `timezone` prop today. DST transitions are handled correctly by `@marianmeres/cron`, but the displayed "next run" will naturally follow local-time semantics.
+
+## Props
+
+| Prop                  | Type                                  | Default         | Description                                          |
+| --------------------- | ------------------------------------- | --------------- | ---------------------------------------------------- |
+| `value`               | `string`                              | `"* * * * *"`   | Cron expression (bindable)                           |
+| `mode`                | `"predefined" \| "manual" \| undefined` | `"predefined"` | Editor mode; `undefined` hides the toggle            |
+| `presets`             | `CronPreset[]`                        | `DEFAULT_PRESETS` | Preset options                                     |
+| `showPresets`         | `boolean`                             | `true`          | (Ignored when `mode` is defined)                     |
+| `showFields`          | `boolean`                             | `true`          | (Ignored when `mode` is defined)                     |
+| `showRawInput`        | `boolean`                             | `true`          | (Ignored when `mode` is defined)                     |
+| `showDescription`     | `boolean`                             | `true`          | (Ignored when `mode` is defined)                     |
+| `showNextRun`         | `boolean`                             | `true`          | (Ignored when `mode` is defined)                     |
+| `onchange`            | `(expr, valid) => void`               | -               | Fires on every valid or invalid change               |
+| `unstyled`            | `boolean`                             | `false`         | Skip stuic base classes (user provides all styling)  |
+| `class`               | `string`                              | -               | Wrapper class                                        |
+| `el`                  | `HTMLElement`                         | -               | Bindable wrapper element                             |
+| `classFields`/`classField`/`classFieldLabel`/`classFieldInput`/`classPreset`/`classRaw`/`classSummary`/`classToggleButton` | `string` | - | Per-element class overrides |
+
+Plus all standard `InputWrap` wrapper class props (`classLabel`, `classLabelBox`, `classInputBox`, `classInputBoxWrap`, `classInputBoxWrapInvalid`, `classDescBox`, `classBelowBox`) — same pattern as every other `Field*` component.
+
+## Accessibility notes
+
+- The preset select has `aria-label="Cron schedule preset"`.
+- Each of the 5 field inputs has `aria-label` combining the short label and its range (e.g. `"Min (0-59)"`).
+- The mode toggle button has a dynamic `aria-label` that reflects the target mode.
+- Validation errors are announced via the underlying `InputWrap`'s validation message region.
+
+## Limitations
+
+- **No timezone override** — uses host local time.
+- **Validation happens on full expression** — no per-field pre-validation; a malformed single field makes the whole expression invalid.
+- **Preset match is exact** — if a user's expression is semantically equivalent but formatted differently (e.g. `"0 0 * * 0"` vs `"0 0 * * 7"`) the preset picker shows "Custom".

package/dist/components/CronInput/cron-next-run.svelte.d.ts

@@ -1,6 +1,17 @@
 /**
  * A reactive helper that parses a cron expression and computes the next run time,
  * updating automatically every minute.
+ *
+ * ⚠️ **You must call `destroy()` when done** — the internal interval does not
+ * clean itself up. In a Svelte component:
+ *
+ * ```ts
+ * import { onDestroy } from "svelte";
+ * const nr = new CronNextRun("0 9 * * *");
+ * onDestroy(() => nr.destroy());
+ * ```
+ *
+ * Forgetting this will leak a 60s-interval timer for the lifetime of the page.
  */
 export declare class CronNextRun {
     #private;

package/dist/components/CronInput/cron-next-run.svelte.js

@@ -2,6 +2,17 @@ import { CronParser } from "@marianmeres/cron";
 /**
  * A reactive helper that parses a cron expression and computes the next run time,
  * updating automatically every minute.
+ *
+ * ⚠️ **You must call `destroy()` when done** — the internal interval does not
+ * clean itself up. In a Svelte component:
+ *
+ * ```ts
+ * import { onDestroy } from "svelte";
+ * const nr = new CronNextRun("0 9 * * *");
+ * onDestroy(() => nr.destroy());
+ * ```
+ *
+ * Forgetting this will leak a 60s-interval timer for the lifetime of the page.
  */
 export class CronNextRun {
     #expression = $state("");

package/dist/components/CronInput/index.css

@@ -10,7 +10,6 @@
 	--stuic-cron-input-section-gap: 0.25rem;
 	--stuic-cron-input-field-label-text: var(--stuic-color-muted-foreground);
 	--stuic-cron-input-summary-text: var(--stuic-color-muted-foreground);
-	--stuic-cron-input-error-text: var(--stuic-color-destructive);
 	--stuic-cron-input-field-bg: var(--stuic-color-background);
 	--stuic-cron-input-field-border: var(--stuic-color-border);
 	--stuic-cron-input-field-border-focus: var(--stuic-color-primary);
@@ -192,13 +191,6 @@
 		line-height: 1.4;
 	}
 
-	/* Error message */
-	.stuic-cron-input-error {
-		color: var(--stuic-cron-input-error-text);
-		font-size: 0.8125rem;
-		line-height: 1.4;
-	}
-
 	/* Mode toggle button */
 	.stuic-cron-input-content + .toggle-btn {
 		color: var(--stuic-input-localized-toggle-text);