@marianmeres/stuic 3.142.1 → 3.144.0

package/AGENTS.md

@@ -53,6 +53,9 @@ Theme CSS files are not bundled in this package — they're provided by `@marian
 5. Create components without `unstyled`, `class`, `el` props
 6. Use `dark:` Tailwind prefix when CSS vars handle dark mode
 7. Import CSS inside components — centralize in `src/lib/index.css`
+   (**exception:** subpath-export components with optional peer deps — `MarkdownEditor`,
+   `CommentInput` — import their own `index.css` locally so their styles don't ship to
+   barrel-only consumers. Enforced by `src/lib/barrel-optional-peers.test.ts`.)
 8. Declare component tokens at `:root` that reference shared structural tokens (use fallback pattern instead)
 
 ### CSS Variable Pattern

package/README.md

@@ -27,6 +27,29 @@ npm install @marianmeres/stuic
 </Modal>
 ```
 
+## Subpath exports
+
+Most of the library is on the main entry. A few things live behind subpaths:
+
+| Subpath                               | Contents                                                      |
+| ------------------------------------- | ------------------------------------------------------------- |
+| `@marianmeres/stuic`                  | Components, actions, icons, utils — everything below excepted |
+| `@marianmeres/stuic/utils`            | Utilities only, without pulling in components                 |
+| `@marianmeres/stuic/phone-validation` | Phone validation helpers                                      |
+| `@marianmeres/stuic/markdown-editor`  | `MarkdownEditor` — requires optional peer deps                |
+| `@marianmeres/stuic/comment-input`    | `CommentInput` — requires optional peer deps                  |
+
+The last two are **not** on the main entry by design: they depend on Milkdown and
+CodeMirror, which are declared as _optional_ peer dependencies. Keeping them off the
+barrel means consumers who don't use them never have to install that stack — and,
+more importantly, their builds don't fail for want of it.
+
+```ts
+import { CommentInput } from "@marianmeres/stuic/comment-input";
+```
+
+See each component's README for the peer set to install.
+
 ## Theming System
 
 STUIC uses a 4-layer CSS variable token system:

package/dist/components/Checkout/CheckoutAddressForm.svelte

@@ -5,8 +5,10 @@
 	import type { TranslateFn } from "../../types.js";
 	import type { Props as FieldCountryProps } from "../Input/FieldCountry.svelte";
 	import type { Props as FieldPhoneNumberProps } from "../Input/FieldPhoneNumber.svelte";
+	import type { Props as FieldSelectProps } from "../Input/FieldSelect.svelte";
 	import type {
 		CheckoutAddressData,
+		CheckoutSubdivisionOption,
 		CheckoutValidationError,
 	} from "./_internal/checkout-types.js";
 
@@ -87,6 +89,71 @@
 		 */
 		countryNames?: Record<string, string>;
 
+		/**
+		 * Subdivision (state/province/region) lists keyed by UPPERCASE ISO alpha-2
+		 * country code. When the currently selected `address.country` has a
+		 * non-empty entry, the `state_or_region` field renders as a fixed select
+		 * over these options (storing the option `code`); for every other country
+		 * it stays the default free-text input, whose value is never touched.
+		 * stuic ships no subdivision data — pass exactly the countries your
+		 * checkout logic keys on (tax, shipping). Default: undefined (free text
+		 * everywhere, current behavior).
+		 *
+		 * When the built-in select is active, a stored value is reconciled
+		 * against the list: an exact `code` match (case-insensitive) is
+		 * normalized to the canonical code, an exact `name` match ("Michigan")
+		 * is rewritten to its `code` ("MI"), and anything else is left
+		 * untouched and renders as unselected — surfaced by required-validation
+		 * rather than destroyed. Reconciliation is skipped when the `stateField`
+		 * snippet replaces the field — a custom control owns its value.
+		 *
+		 * Country edits made through this form flip the mode live even for a
+		 * plain (non-`$state`) `address` object; external mutations of a plain
+		 * object are not observable — pass a `$state` object for those.
+		 */
+		subdivisions?: Record<string, CheckoutSubdivisionOption[]>;
+
+		/**
+		 * Whether `state_or_region` is required while the subdivision select is
+		 * active (i.e. the current country has a `subdivisions` entry). Also
+		 * accepts a per-country predicate receiving the UPPERCASE ISO code.
+		 * Countries without a list keep the plain `requiredFields` behavior
+		 * (as does a `requiredFields` entry for "state_or_region", which wins
+		 * regardless). Default: true.
+		 */
+		subdivisionRequired?: boolean | ((countryIso: string) => boolean);
+
+		/**
+		 * Override the state/region field with a custom control (parity with
+		 * `countryField`). When provided, replaces the built-in field in both
+		 * modes; `options` is the active country's subdivision list, or null
+		 * when the free-text input would apply.
+		 */
+		stateField?: Snippet<
+			[
+				{
+					/** Current state/region value */
+					value: string;
+					/** Called when the value changes */
+					onchange: (value: string) => void;
+					/** Error message for this field (if any) */
+					error?: string;
+					/** Field label text */
+					label: string;
+					/** HTML id attribute for the input */
+					id: string;
+					/** Active country's subdivision list, or null (free-text mode) */
+					options: CheckoutSubdivisionOption[] | null;
+				},
+			]
+		>;
+
+		/**
+		 * Extra props forwarded to the internal FieldSelect when the subdivision
+		 * select is active (parity with `countryFieldProps`).
+		 */
+		stateFieldProps?: Partial<FieldSelectProps>;
+
 		/** Extra props forwarded to the internal FieldPhoneNumber component. */
 		phoneFieldProps?: Partial<FieldPhoneNumberProps>;
 
@@ -109,6 +176,7 @@
 	import FieldCountry from "../Input/FieldCountry.svelte";
 	import FieldInput from "../Input/FieldInput.svelte";
 	import FieldPhoneNumber from "../Input/FieldPhoneNumber.svelte";
+	import FieldSelect from "../Input/FieldSelect.svelte";
 	import { validatePhoneNumber } from "../Input/phone-validation.js";
 	import { t_default } from "./_internal/checkout-i18n-defaults.js";
 	import { createEmptyAddress } from "./_internal/checkout-utils.js";
@@ -125,6 +193,10 @@
 		countryList,
 		preferredCountries,
 		countryNames,
+		subdivisions,
+		subdivisionRequired = true,
+		stateField,
+		stateFieldProps,
 		phoneFieldProps,
 		countryFieldProps,
 		t: tProp,
@@ -147,6 +219,56 @@
 	let containerWidth = $state(0);
 	let isSmall = $derived(containerWidth > 0 && containerWidth < 480);
 
+	// Subdivision select mode (see the `subdivisions` prop) --------------------
+	// Local mirror of `address.country` (writable derived). The select/input
+	// mode must react to country edits even when the consumer passed a plain
+	// (non-$state) address object, whose deep mutations Svelte cannot observe —
+	// so every country write that goes through this form also overrides the
+	// mirror directly, while reactive addresses and prop replacement resync it
+	// through the derived expression. External mutations of a plain object stay
+	// unobservable (true for every field).
+	let _country = $derived(address.country ?? "");
+
+	function setCountry(v: string) {
+		address.country = v;
+		_country = v;
+	}
+
+	let _countryCC = $derived(_country.trim().toUpperCase());
+
+	let _subdivisionList = $derived.by(() => {
+		const list = _countryCC ? subdivisions?.[_countryCC] : undefined;
+		return list?.length ? list : null;
+	});
+
+	let _subdivisionIsRequired = $derived(
+		isRequired("state_or_region") ||
+			(typeof subdivisionRequired === "function"
+				? subdivisionRequired(_countryCC)
+				: subdivisionRequired)
+	);
+
+	// Reconcile a pre-existing value whenever the built-in select becomes
+	// active: legacy free-text rows ("Michigan", "mi") self-heal to the
+	// canonical code ("MI"); anything unrecognized is left untouched (renders
+	// unselected, caught by required-validation) — never destroyed. Converges:
+	// the write triggers one re-run which then matches the code branch with
+	// nothing to change. Skipped entirely under the `stateField` snippet — a
+	// custom control owns its value (a controlled combobox writing in-progress
+	// text through `onchange` must not have it rewritten mid-typing).
+	$effect(() => {
+		if (stateField) return;
+		const list = _subdivisionList;
+		if (!list) return;
+		const raw = address.state_or_region ?? "";
+		const needle = raw.trim().toLowerCase();
+		if (!needle) return;
+		const hit =
+			list.find((o) => o.code.toLowerCase() === needle) ??
+			list.find((o) => o.name.trim().toLowerCase() === needle);
+		if (hit && raw !== hit.code) address.state_or_region = hit.code;
+	});
+
 	let _class = $derived(
 		unstyled ? classProp : twMerge("stuic-checkout-address", classProp)
 	);
@@ -154,12 +276,12 @@
 	// Imperative API ----------------------------------------------------------
 	// Field refs collected during render so consumers can trigger validation
 	// without waiting for native form submission. Refs stay undefined for
-	// fields hidden via the `fields` prop or replaced by the `countryField`
-	// snippet — `validateAllFields` skips nullish entries.
+	// fields hidden via the `fields` prop or replaced by the `countryField`/
+	// `stateField` snippets — `validateAllFields` skips nullish entries.
 	let nameField = $state<FieldInput>();
 	let streetField = $state<FieldInput>();
 	let cityField = $state<FieldInput>();
-	let stateField = $state<FieldInput>();
+	let stateFieldRef = $state<FieldInput | FieldSelect>();
 	let postalCodeField = $state<FieldInput>();
 	let countryFieldRef = $state<FieldCountry>();
 	let phoneField = $state<FieldPhoneNumber>();
@@ -170,7 +292,7 @@
 			nameField,
 			streetField,
 			cityField,
-			stateField,
+			stateFieldRef,
 			postalCodeField,
 			countryFieldRef,
 			phoneField,
@@ -276,22 +398,63 @@
 				/>
 			{/if}
 			{#if fields?.state_or_region !== false}
-				<!-- svelte-ignore binding_property_non_reactive -->
-				<FieldInput
-					bind:this={stateField}
-					bind:value={address.state_or_region}
-					label={t("checkout.address.state_or_region_label")}
-					labelLeftBreakpoint={0}
-					placeholder={t("checkout.address.state_or_region_placeholder")}
-					required={isRequired("state_or_region")}
-					name="{label}-state_or_region"
-					id="{label}-state_or_region"
-					validate={{
-						customValidator(val) {
-							return fieldError("state_or_region") || "";
+				{#if stateField}
+					{@render stateField({
+						value: address.state_or_region ?? "",
+						onchange: (v) => {
+							address.state_or_region = v;
 						},
-					}}
-				/>
+						error: fieldError("state_or_region"),
+						label: t("checkout.address.state_or_region_label"),
+						id: `${label}-state_or_region`,
+						options: _subdivisionList,
+					})}
+				{:else if _subdivisionList}
+					<FieldSelect
+						bind:this={stateFieldRef}
+						bind:value={
+							() => address.state_or_region ?? "",
+							(v) => {
+								address.state_or_region = String(v ?? "");
+							}
+						}
+						options={[
+							{
+								label: t("checkout.address.state_or_region_select_placeholder"),
+								value: "",
+							},
+							..._subdivisionList.map((o) => ({ label: o.name, value: o.code })),
+						]}
+						label={t("checkout.address.state_or_region_label")}
+						labelLeftBreakpoint={0}
+						required={_subdivisionIsRequired}
+						name="{label}-state_or_region"
+						id="{label}-state_or_region"
+						validate={{
+							customValidator(val) {
+								return fieldError("state_or_region") || "";
+							},
+						}}
+						{...stateFieldProps}
+					/>
+				{:else}
+					<!-- svelte-ignore binding_property_non_reactive -->
+					<FieldInput
+						bind:this={stateFieldRef}
+						bind:value={address.state_or_region}
+						label={t("checkout.address.state_or_region_label")}
+						labelLeftBreakpoint={0}
+						placeholder={t("checkout.address.state_or_region_placeholder")}
+						required={isRequired("state_or_region")}
+						name="{label}-state_or_region"
+						id="{label}-state_or_region"
+						validate={{
+							customValidator(val) {
+								return fieldError("state_or_region") || "";
+							},
+						}}
+					/>
+				{/if}
 			{/if}
 			{#if fields?.postal_code !== false}
 				<!-- svelte-ignore binding_property_non_reactive -->
@@ -318,19 +481,16 @@
 	{#if fields?.country !== false}
 		{#if countryField}
 			{@render countryField({
-				value: address.country,
-				onchange: (v) => {
-					address.country = v;
-				},
+				value: _country,
+				onchange: setCountry,
 				error: fieldError("country"),
 				label: t("checkout.address.country_label"),
 				id: `${label}-country`,
 			})}
 		{:else}
-			<!-- svelte-ignore binding_property_non_reactive -->
 			<FieldCountry
 				bind:this={countryFieldRef}
-				bind:value={address.country}
+				bind:value={() => _country, setCountry}
 				label={t("checkout.address.country_label")}
 				placeholder={t("checkout.address.country_placeholder")}
 				required={isRequired("country")}

package/dist/components/Checkout/CheckoutAddressForm.svelte.d.ts

@@ -4,7 +4,8 @@ import type { HTMLAttributes } from "svelte/elements";
 import type { TranslateFn } from "../../types.js";
 import type { Props as FieldCountryProps } from "../Input/FieldCountry.svelte";
 import type { Props as FieldPhoneNumberProps } from "../Input/FieldPhoneNumber.svelte";
-import type { CheckoutAddressData, CheckoutValidationError } from "./_internal/checkout-types.js";
+import type { Props as FieldSelectProps } from "../Input/FieldSelect.svelte";
+import type { CheckoutAddressData, CheckoutSubdivisionOption, CheckoutValidationError } from "./_internal/checkout-types.js";
 export interface Props extends Omit<HTMLAttributes<HTMLFieldSetElement>, "children"> {
     /**
      * Bindable address data. Default: createEmptyAddress().
@@ -71,6 +72,65 @@ export interface Props extends Omit<HTMLAttributes<HTMLFieldSetElement>, "childr
      * values are the localized name. Missing keys fall back to English.
      */
     countryNames?: Record<string, string>;
+    /**
+     * Subdivision (state/province/region) lists keyed by UPPERCASE ISO alpha-2
+     * country code. When the currently selected `address.country` has a
+     * non-empty entry, the `state_or_region` field renders as a fixed select
+     * over these options (storing the option `code`); for every other country
+     * it stays the default free-text input, whose value is never touched.
+     * stuic ships no subdivision data — pass exactly the countries your
+     * checkout logic keys on (tax, shipping). Default: undefined (free text
+     * everywhere, current behavior).
+     *
+     * When the built-in select is active, a stored value is reconciled
+     * against the list: an exact `code` match (case-insensitive) is
+     * normalized to the canonical code, an exact `name` match ("Michigan")
+     * is rewritten to its `code` ("MI"), and anything else is left
+     * untouched and renders as unselected — surfaced by required-validation
+     * rather than destroyed. Reconciliation is skipped when the `stateField`
+     * snippet replaces the field — a custom control owns its value.
+     *
+     * Country edits made through this form flip the mode live even for a
+     * plain (non-`$state`) `address` object; external mutations of a plain
+     * object are not observable — pass a `$state` object for those.
+     */
+    subdivisions?: Record<string, CheckoutSubdivisionOption[]>;
+    /**
+     * Whether `state_or_region` is required while the subdivision select is
+     * active (i.e. the current country has a `subdivisions` entry). Also
+     * accepts a per-country predicate receiving the UPPERCASE ISO code.
+     * Countries without a list keep the plain `requiredFields` behavior
+     * (as does a `requiredFields` entry for "state_or_region", which wins
+     * regardless). Default: true.
+     */
+    subdivisionRequired?: boolean | ((countryIso: string) => boolean);
+    /**
+     * Override the state/region field with a custom control (parity with
+     * `countryField`). When provided, replaces the built-in field in both
+     * modes; `options` is the active country's subdivision list, or null
+     * when the free-text input would apply.
+     */
+    stateField?: Snippet<[
+        {
+            /** Current state/region value */
+            value: string;
+            /** Called when the value changes */
+            onchange: (value: string) => void;
+            /** Error message for this field (if any) */
+            error?: string;
+            /** Field label text */
+            label: string;
+            /** HTML id attribute for the input */
+            id: string;
+            /** Active country's subdivision list, or null (free-text mode) */
+            options: CheckoutSubdivisionOption[] | null;
+        }
+    ]>;
+    /**
+     * Extra props forwarded to the internal FieldSelect when the subdivision
+     * select is active (parity with `countryFieldProps`).
+     */
+    stateFieldProps?: Partial<FieldSelectProps>;
     /** Extra props forwarded to the internal FieldPhoneNumber component. */
     phoneFieldProps?: Partial<FieldPhoneNumberProps>;
     /** Extra props forwarded to the internal FieldCountry component. */

package/dist/components/Checkout/CheckoutShippingStep.svelte

@@ -99,6 +99,7 @@
 		 * Props forwarded to both inner `CheckoutAddressForm` instances (shipping
 		 * and, when visible, billing). Use this to configure `phoneFieldProps`,
 		 * `countryFieldProps`, `preferredCountries`, `countryList`, `countryNames`,
+		 * `subdivisions`, `subdivisionRequired`, `stateFieldProps`,
 		 * `requiredFields`, or `fields` without replacing the entire left column
 		 * via the `leftColumn` snippet.
 		 *

package/dist/components/Checkout/CheckoutShippingStep.svelte.d.ts

@@ -55,6 +55,7 @@ export interface Props extends Omit<HTMLAttributes<HTMLDivElement>, "children">
      * Props forwarded to both inner `CheckoutAddressForm` instances (shipping
      * and, when visible, billing). Use this to configure `phoneFieldProps`,
      * `countryFieldProps`, `preferredCountries`, `countryList`, `countryNames`,
+     * `subdivisions`, `subdivisionRequired`, `stateFieldProps`,
      * `requiredFields`, or `fields` without replacing the entire left column
      * via the `leftColumn` snippet.
      *

package/dist/components/Checkout/README.md

@@ -126,6 +126,57 @@ interface CheckoutValidationError {
 
 The step component **does not auto-advance**. It calls `onContinue` when the user clicks "Continue"; the consumer decides whether to actually advance, retry, or show errors.
 
+## Country-aware state/region select (`subdivisions`)
+
+By default `CheckoutAddressForm` renders `state_or_region` as free text. For
+countries where downstream logic keys on an exact subdivision code (US
+sales-tax tables, shipping zones), pass `subdivisions` — lists keyed by
+UPPERCASE ISO alpha-2 country code. When the selected country has an entry,
+the field swaps to a fixed select storing the canonical `code`; every other
+country keeps the free-text input, verbatim. stuic ships **no** subdivision
+data — pass exactly what your app needs:
+
+```svelte
+<CheckoutAddressForm
+	bind:address
+	subdivisions={{
+		US: [
+			{ code: "AL", name: "Alabama" },
+			{ code: "AK", name: "Alaska" },
+			// ... full USPS list
+		],
+	}}
+/>
+```
+
+Behavior details:
+
+- **Stored value is always the `code`** ("MI") — same wire shape as free text,
+  no server contract change.
+- **Prefill reconciliation:** entering select mode with a legacy value
+  self-heals it — `"mi"` → `"MI"`, `"Michigan"` → `"MI"` (written back into
+  the bound `address`). Unrecognized values are left untouched and render as
+  unselected, surfaced by validation rather than destroyed. Applies only to
+  the built-in select — the `stateField` snippet owns its value entirely.
+- **Country switching never clears the field** — a US → CA → US round-trip
+  restores "MI".
+- **Required:** while the select is active the field is required by default
+  (`subdivisionRequired`, also accepts a per-country predicate
+  `(countryIso) => boolean`). Countries without a list keep the plain
+  `requiredFields` behavior.
+- `stateFieldProps` forwards extras to the internal `FieldSelect`; the
+  `stateField` snippet replaces the field entirely (receives the active
+  `options`, or `null` in free-text mode) — parity with
+  `countryField`/`countryFieldProps`.
+- i18n: the select's empty option uses
+  `checkout.address.state_or_region_select_placeholder` (default `"Select…"`).
+- Forward through composite steps via
+  `CheckoutShippingStep.addressFormProps`.
+
+Note: the `validateAddress()` utility has no access to the `subdivisions`
+config, so it does not enforce subdivision-required — use the component's
+imperative `validate()` (step containers already do).
+
 ## Price arithmetic
 
 **All monetary values are integers in the smallest currency unit (cents).** This applies to `CheckoutOrderLineItem.price`, `CheckoutDeliveryOption.price`, `CheckoutDeliveryOption.free_above`, and every field in `CheckoutOrderTotals`.

package/dist/components/Checkout/_internal/checkout-i18n-defaults.js

@@ -67,6 +67,7 @@ const DEFAULTS = {
     "checkout.address.city_placeholder": "",
     "checkout.address.state_or_region_label": "State / Region",
     "checkout.address.state_or_region_placeholder": "",
+    "checkout.address.state_or_region_select_placeholder": "Select…",
     "checkout.address.postal_code_label": "Postal Code",
     "checkout.address.postal_code_placeholder": "",
     "checkout.address.country_label": "Country",

package/dist/components/Checkout/_internal/checkout-types.d.ts

@@ -10,6 +10,17 @@ export interface CheckoutStep {
     /** Whether this step can be navigated to (clicked). Default: true for past steps */
     navigable?: boolean;
 }
+/**
+ * One selectable subdivision (state/province/region) for the
+ * `CheckoutAddressForm` `subdivisions` prop. stuic ships no subdivision
+ * data — consumers pass the lists for the countries they care about.
+ */
+export interface CheckoutSubdivisionOption {
+    /** Canonical stored value — ISO 3166-2 subdivision suffix / USPS code (e.g. "MI"). */
+    code: string;
+    /** Display name (e.g. "Michigan"). */
+    name: string;
+}
 export interface CheckoutAddressData {
     name: string;
     street: string;

package/dist/components/Checkout/index.d.ts

@@ -12,5 +12,5 @@ export { default as CheckoutReviewStep, type Props as CheckoutReviewStepProps, }
 export { default as CheckoutShippingStep, type Props as CheckoutShippingStepProps, } from "./CheckoutShippingStep.svelte";
 export { default as CheckoutConfirmStep, type Props as CheckoutConfirmStepProps, } from "./CheckoutConfirmStep.svelte";
 export { default as CheckoutCompleteStep, type Props as CheckoutCompleteStepProps, } from "./CheckoutCompleteStep.svelte";
-export type { CheckoutStep, CheckoutAddressData, CheckoutCustomerFormData, CheckoutLoginFormData, CheckoutOrderLineItem, CheckoutOrderTotals, CheckoutDeliveryOption, CheckoutDeliverySnapshot, CheckoutOrderData, CheckoutValidationError, } from "./_internal/checkout-types.js";
+export type { CheckoutStep, CheckoutAddressData, CheckoutSubdivisionOption, CheckoutCustomerFormData, CheckoutLoginFormData, CheckoutOrderLineItem, CheckoutOrderTotals, CheckoutDeliveryOption, CheckoutDeliverySnapshot, CheckoutOrderData, CheckoutValidationError, } from "./_internal/checkout-types.js";
 export { defaultFormatPrice, validateEmail, validateAddress, validateCustomerForm, validateLoginForm, createEmptyAddress, createEmptyCustomerFormData, createEmptyLoginFormData, addressesEqual, } from "./_internal/checkout-utils.js";

package/dist/components/CommentInput/CommentInput.svelte

@@ -143,6 +143,7 @@
 	import { Button } from "../Button/index.js";
 	import Thc from "../Thc/Thc.svelte";
 	import { MarkdownEditor } from "../MarkdownEditor/index.js";
+	import "./index.css";
 
 	let {
 		value = $bindable(""),

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

@@ -110,6 +110,7 @@ export interface Props extends InputWrapClassProps {
     classFooter?: string;
     style?: string;
 }
+import "./index.css";
 declare const CommentInput: import("svelte").Component<Props, {
     validate: () => ValidationResult | undefined;
     clearValidation: () => void;

package/dist/components/CommentInput/README.md

@@ -12,9 +12,14 @@ lightweight, opinionated wrapper for the common "leave a comment / reply" use
 case: a clean minimal toolbar, an avatar, a submit button, and
 ⌘/Ctrl+Enter-to-send — without you having to wire any of it up.
 
+Because it embeds `MarkdownEditor`, it is shipped as an **optional subpath export**
+(`@marianmeres/stuic/comment-input`), separate from the main barrel — so the heavy
+editor dependencies never reach consumers who don't use it. Importing it from
+`@marianmeres/stuic` will not work.
+
 ```svelte
 <script>
-	import { CommentInput } from "@marianmeres/stuic";
+	import { CommentInput } from "@marianmeres/stuic/comment-input";
 
 	let value = $state("");
 
@@ -49,6 +54,11 @@ This is the same peer set as `MarkdownEditor` — see its README for the
 authoritative list. If they aren't installed, the surface stays empty and a
 console error explains why.
 
+> **CSS is imported locally** by this component, not via the central
+> `src/lib/index.css`. Deliberate deviation from the usual STUIC convention,
+> required so these styles ship only to subpath users. Same as `MarkdownEditor`;
+> see `index.css` for the rationale.
+
 ## Toolbar
 
 `toolbar` accepts `true` (the default), `false` (hidden), or an ordered

package/dist/components/CommentInput/index.css

@@ -1,6 +1,19 @@
 /******************************************************************************
   CommentInput
 
+  NOTE — intentional deviation from the usual STUIC CSS convention.
+  Every other component's `index.css` is `@import`-ed into the central
+  `src/lib/index.css`. This component is NOT: because it embeds `MarkdownEditor`
+  it is an OPTIONAL subpath export (`@marianmeres/stuic/comment-input`) kept off
+  the main barrel, so the heavy Milkdown/CodeMirror peers never reach consumers
+  who don't use it. Centralizing its CSS would ship these styles to every
+  consumer anyway. Instead `CommentInput.svelte` imports THIS file locally; the
+  package's `sideEffects` glob (all css files) keeps the import for real users.
+
+  `MarkdownEditor/index.css` arrives on its own — `MarkdownEditor.svelte`
+  imports it locally too — so do NOT `@import` it here (it would double-inject
+  for anyone using both components).
+
   A GitHub-style comment composer built on top of `MarkdownEditor` (a rich
   WYSIWYG / source surface) with an avatar gutter and a submit/cancel footer.
 

package/dist/index.css

@@ -71,7 +71,9 @@ In practice:
 @import "./components/LoginOrRegisterForm/index.css";
 @import "./components/Checkout/index.css";
 @import "./components/CommandMenu/index.css";
-@import "./components/CommentInput/index.css";
+/* NOTE: CommentInput/index.css is deliberately NOT imported here — same reason as
+   MarkdownEditor's. It is a subpath-export component and imports its own CSS
+   locally (see components/CommentInput/index.css). Do not re-add. */
 @import "./components/ContactUsForm/index.css";
 @import "./components/CronInput/index.css";
 @import "./components/DataTable/index.css";

package/dist/index.d.ts

@@ -38,7 +38,6 @@ export * from "./components/Checkout/index.js";
 export * from "./components/Collapsible/index.js";
 export * from "./components/ColorScheme/index.js";
 export * from "./components/CommandMenu/index.js";
-export * from "./components/CommentInput/index.js";
 export * from "./components/ContactUsForm/index.js";
 export * from "./components/CronInput/index.js";
 export * from "./components/DataTable/index.js";

package/dist/index.js

@@ -39,7 +39,11 @@ export * from "./components/Checkout/index.js";
 export * from "./components/Collapsible/index.js";
 export * from "./components/ColorScheme/index.js";
 export * from "./components/CommandMenu/index.js";
-export * from "./components/CommentInput/index.js";
+// NOTE: CommentInput is deliberately NOT exported here. It embeds MarkdownEditor,
+// whose optional @milkdown/* + @codemirror/* peers would then be pulled into the
+// root entry graph of every consumer. It ships as the `@marianmeres/stuic/comment-input`
+// subpath export instead, mirroring `@marianmeres/stuic/markdown-editor`.
+// Guarded by src/lib/barrel-optional-peers.test.ts — do not re-add.
 export * from "./components/ContactUsForm/index.js";
 export * from "./components/CronInput/index.js";
 export * from "./components/DataTable/index.js";

package/docs/architecture.md

@@ -80,6 +80,17 @@ src/lib/
 
 **DO NOT** use `import './index.css'` inside component `.svelte` files.
 
+**Exception — subpath-export components.** A component whose peer dependencies are
+declared _optional_ (`MarkdownEditor`, `CommentInput`) is kept off the root barrel and
+shipped behind its own subpath export, so those peers never enter the entry graph of
+consumers who don't use it. Such a component imports its own `index.css` locally and is
+**not** `@import`-ed into `src/lib/index.css` — centralizing it would ship the styles to
+every consumer, defeating the isolation. `sideEffects: ["**/*.css"]` in `package.json`
+keeps the local import alive for real users.
+
+Both halves are enforced by `src/lib/barrel-optional-peers.test.ts` — adding such a
+component to the barrel (or its CSS to the central stylesheet) fails the suite.
+
 ---
 
 ## Data Flow
@@ -151,9 +162,20 @@ Theme CSS files are provided by the `@marianmeres/design-tokens` package (a regu
 ### Package Exports
 
 ```json
-".":            Main entry (components, utils, actions, icons, theme types)
+".":                  Main entry (components, utils, actions, icons, theme types)
+"./utils":            Utilities only
+"./phone-validation": Phone validation helpers
+"./markdown-editor":  MarkdownEditor  — optional peer deps, local CSS
+"./comment-input":    CommentInput    — optional peer deps, local CSS
 ```
 
+The last two are deliberately **off** the main entry: they reach `@milkdown/*` and
+`@codemirror/*`, which are optional peers. A consumer that has not installed those
+peers gets a hard bundler error (rolldown reports every named import from the
+unresolved stub as `MISSING_EXPORT`) if the root barrel can reach them — even though
+the editor backends sit behind `await import()`, because the specifiers are static
+literals that a bundler must still resolve at build time.
+
 ---
 
 ## Security Boundaries

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@marianmeres/stuic",
-	"version": "3.142.1",
+	"version": "3.144.0",
 	"packageManager": "pnpm@11.5.0",
 	"scripts": {
 		"dev": "vite dev",
@@ -54,6 +54,11 @@
 			"types": "./dist/components/MarkdownEditor/index.d.ts",
 			"svelte": "./dist/components/MarkdownEditor/index.js",
 			"default": "./dist/components/MarkdownEditor/index.js"
+		},
+		"./comment-input": {
+			"types": "./dist/components/CommentInput/index.d.ts",
+			"svelte": "./dist/components/CommentInput/index.js",
+			"default": "./dist/components/CommentInput/index.js"
 		}
 	},
 	"peerDependencies": {
@@ -72,8 +77,6 @@
 		"@milkdown/prose": "^7.0.0",
 		"@milkdown/transformer": "^7.0.0",
 		"@milkdown/utils": "^7.0.0",
-		"dompurify": "^3.0.0",
-		"marked": "^18.0.0",
 		"svelte": "^5.0.0"
 	},
 	"peerDependenciesMeta": {
@@ -121,12 +124,6 @@
 		},
 		"@milkdown/utils": {
 			"optional": true
-		},
-		"dompurify": {
-			"optional": true
-		},
-		"marked": {
-			"optional": true
 		}
 	},
 	"devDependencies": {
@@ -157,11 +154,9 @@
 		"@tailwindcss/vite": "^4.3.1",
 		"@types/node": "^25.9.4",
 		"@vitest/browser-playwright": "^4.1.9",
-		"dompurify": "^3.4.11",
 		"dotenv": "^16.6.1",
 		"eslint": "^9.39.4",
 		"globals": "^16.5.0",
-		"marked": "^18.0.5",
 		"playwright": "^1.61.1",
 		"prettier": "^3.9.0",
 		"prettier-plugin-svelte": "^3.5.2",