svelte-fluentui 1.1.0 → 1.2.0

package/README.md

@@ -2,6 +2,15 @@
 
 A comprehensive Svelte wrapper library for Microsoft FluentUI web components (v2.6.x), providing a seamless way to use FluentUI components in Svelte applications.
 
+## What's New in v1.2.0
+
+- **`Divider` — `orientation` and `role` props now forwarded** — the wrapper previously only exposed `class` and `style`, so vertical dividers and `role="presentation"` (for decorative separators that should be skipped by screen readers) weren't expressible through the Svelte API. `<fluent-divider>` natively supports both via fast-foundation; the wrapper just forwards them. Defaults preserved (`orientation="horizontal"`, `role="separator"`) so every existing call site renders identically. First proper demo page at `/components/divider` — the previous `/divider` route was an HMR sandbox and the components-list link to `/components/divider` was a 404.
+- **`Select` rewritten as a custom component** — the wrapped `<fluent-select>` rendered its dropdown listbox inside its own shadow DOM with a static `--max-height`, so inside Dialogs and other overflow-hidden ancestors the option list extended past the viewport with no scroll cutoff. New custom Select portals the listbox to `document.body` via `PositioningRegion` (Floating-UI), so it escapes any clipping ancestor and stays inside the viewport regardless of where the trigger sits. Full keyboard wiring (Arrow/Home/End/Enter/Space/Escape/Tab, single-char type-ahead with cycle-through-matches), multi-mode renders an always-expanded inline listbox matching FluentUI Blazor, and a hidden `<input>` keeps native form submission working. Public API mostly preserved; `value` widened to `string | string[]` for multi mode, `open` is now bindable, and `position` means "force placement" rather than the old static attribute.
+- **`PositioningRegion` — new `availableHeight` prop** — writes the computed remaining viewport height into the `--available-height` CSS custom property on the floating element on every reposition, so dropdowns can cap their max-height with `max-height: var(--available-height, <fallback>)` instead of hard-coding a value that overflows on small screens or near viewport edges. Works alongside `matchWidth` in a single `size()` middleware pass.
+- **`.fluent-value-label` — new canonical class for inline value labels next to a control** — separates field labels (the bold, stacked-above text that names a form field) from value labels (the inline text next to a single control that describes the value, e.g. "Remember me" next to a checkbox). Value labels are normal weight with a pointer cursor, matching FluentUI Blazor's pickers and `<fluent-radio>`'s slotted label. `data-disabled` / `data-readonly` on the wrapper drive a `not-allowed` cursor when the host is inactive.
+- **`Checkbox` & `Switch` — inline label fixes** — labels were rendering bold with a text cursor (using the field-label class) and clicks on the label didn't reliably toggle the control when no `id` was passed. Switched to the new `.fluent-value-label` class, and a stable per-instance `fallbackId` is now used as `<label for>` / element `id` when the caller didn't supply one, so label-click-to-toggle works regardless of whether an `id` was passed in. Applies across all three `labelPosition` values (`top` / `start` / `end`).
+- **`Select` & `Combobox` — field-label class consolidated to shared `.fluent-label`** — both components had component-scoped `.select-label` / `.combobox-label` rules that duplicated the canonical `.fluent-label` declarations from `assets/styles/components.scss`. A single library-wide tweak to label styling now lives in one place. After this change, every component that renders a stacked field label uses `.fluent-label`, Field uses its BEM-namespaced `fluent-field__label`, and Checkbox/Switch use `.fluent-value-label` — three classes total, each with a clear semantic role.
+
 ## What's New in v1.1.0
 
 - **`Calendar` — new `disabled` prop for whole-control disabled state** — Calendar previously had `readonly` (blocks interaction, sets `aria-readonly`) but no host-level `disabled`. New `disabled?: boolean` blocks all interaction (day/month/year cells, title-button view switching, prev/next navigation) AND adds visual de-emphasis via `aria-disabled="true"`: drops opacity to `var(--disabled-opacity)`, sets `cursor: not-allowed` on interactive cells. Per-cell `aria-disabled` strikethrough rules are untouched — the new selectors only fire when the HOST has `aria-disabled`. Propagates through the recursive Calendar instances (month/year picker views) and through `DatePicker` to the inner Calendar. Demo "Calendar states" at `/components/forms/calendar` shows Normal / Readonly / Disabled side-by-side.
@@ -10,28 +19,6 @@ A comprehensive Svelte wrapper library for Microsoft FluentUI web components (v2
 - **`Textarea` — drag-resize no longer collapses the focus indicator** — FluentUI's shadow-DOM `:active::after` rule shrank the bottom indicator to a 40%-wide centered stub during any `:active` state, which fired during the resize drag and read as a focus loss. Override injected via `adoptedStyleSheets` restores the full-width indicator while dragging.
 - **Playwright e2e suite** — New `playwright.config.ts` targets fixture pages under `docs/src/routes/test/<feature>/+page.svelte` (intentionally separate from showcase pages so specs stay stable). First feature covered is Autocomplete with 567 lines of specs across two fixture pages.
 
-## What's New in v1.0.0
-
-The first stable release. Headline changes since the rc series:
-
-- **`Calendar` — generic `highlightDates` + `selectDates` function-prop split (replaces `selectDatesHover`)** — two consumer-supplied pure functions of shape `(date: Date) => Date[]` drive the hover preview and the click selection separately, so you can preview a week on hover but commit only 3 days on click. Multiple mode UNIONS the returned group with the existing array (clicked day toggles the whole group); range mode replaces. Consumer functions are authoritative — the calendar no longer re-filters against `disabledDateFunc`, so consumers are free to skip disabled days, jump past them to reach a target count, or include them deliberately for special highlighting. Two new demos: "Range with SelectOneWeek" (hovering any day highlights Mon→Sun, click commits the whole week) and "Multiple with Select3Days" (hover/click selects the day ± 1 neighbor).
-- **`Calendar` — `maxSelectableDays` + `onSelectionError` callback with structured payload** — multiple/range modes now gate every selection against an upper bound. Overflow does NOT modify `selectedDates`; instead fires `onSelectionError({code, message, attempted, current, max})` with a discriminated-union `code` (`"max_selectable_days_exceeded"` for now, future codes won't break consumer dispatch). New exported `CalendarSelectionError` type. Demo "Multiple (max 5 days)" shows the Alert-remount pattern for repeat-error feedback.
-- **`Calendar` — `onDayHover?(date: Date | null) => void` pure-observation callback** — fires with the hovered `Date` regardless of `selectMode` / disabled state (so tooltips can react to inactive days too), and with `null` when the cursor leaves the grid. Distinct from `highlightDates` (which DRIVES rendering); `onDayHover` is for tooltips, analytics, "currently hovering" readouts.
-- **`Calendar` — public type re-exports** — `CalendarView`, `CalendarSelectMode`, `CalendarSelectionError`, `CalendarSelectionErrorCode` now importable from the package entry point.
-- **`Checkbox` — three state-driven message props (`checkedMessage` / `uncheckedMessage` / `intermediateMessage`)** — Switch already had `checkedMessage` / `uncheckedMessage`; Checkbox catches up plus the three-state variant for `withIntermediate`. All three accept `string | Snippet`, rendered as a sibling `.checkbox-message` after the box.
-- **`Checkbox` — `labelPosition="end"` (now the default)** — was `"start"` (label on the LEFT, atypical for forms). New default puts the label after the box `[☐] Label text`. Implemented via flex `order` so a trailing status message stays after the [box, label] pair without flipping.
-- **Docs — per-page SEO metadata via shared `<Meta>` component on all 63 routes** — every page now emits its own `<title>`, description, keywords, canonical, Open Graph, and Twitter Card tags. Browser tabs, bookmarks, and JS-capable crawlers (Google) get the per-page tags; non-JS crawlers (Slack, Discord, Facebook, LinkedIn, X) still see the static `app.html` fallback since the docs site runs as a pure SPA.
-- **Docs — every `<h1>` / `<h2>` / `<h3>` in component pages is now a shareable anchor with a copy-link button on hover** — pure post-render DOM decoration at the layout level, so it works on every existing and future component page automatically. Stable slugified ids, `-2`/`-3` suffixes on collisions, copy-to-clipboard with flash feedback.
-- **Docs — shared `<References>` component replaces hand-rolled references cards on 48 pages** — single source of truth for the references block; `na: true` / `custom: true` variants for "Not available in FluentUI Web Components" and "Custom component" disabled spans with tooltips. Format tweaks now live in one file instead of 48.
-- **Docs — API tables relocated to the BOTTOM of every component page, AFTER the Examples** — the previous layout forced visitors to scroll past dense reference material to reach the examples. New order: `[title + description] → [References] → [Examples] → [API tables]`.
-- **`InputFile` — 2547-line component split across six files for maintainability** — types extracted to `InputFile.types.ts`, utilities + default labels to `InputFile.utils.ts`, ~725 lines of inline CSS to an external SCSS partial, and the three `selectorAppearance` variants pulled into `InputFileSelectorCard.svelte` / `InputFileSelectorButton.svelte` / `InputFileSelectorMinimal.svelte`. Public API unchanged; type-check clean.
-
-### Previously (rc22)
-
-- **`InputFile` chips mode now has an overall progress footer** — the same `Pause all` / `Resume all` / `Retry all` controls plus the aggregate progress bar that list/popover modes already had. Works for both `chipsPosition` values; rendered as a sibling below the chips so layout stays sane regardless of position.
-- **`package.json` `homepage` points at the docs site** — npm's "Homepage" sidebar link now goes to `svelte-fluentui.keenmate.dev` instead of duplicating the GitHub repo link. Two distinct destinations on the package page.
-- **InputFile demo playground persists in localStorage** — the live selector × list × cardSize × chipsPosition mixer at `/components/inputfile` remembers your last configuration across page reloads. Files themselves are not persisted (File objects don't survive JSON).
-
 ## Features
 
 - 🎨 **Complete FluentUI Component Set** - Wraps all major FluentUI web components

package/dist/assets/styles/components.scss

@@ -32,9 +32,9 @@
 	align-items: center;
 }
 
-// Canonical label style used by form components (TextField, Select,
-// Autocomplete, Radio, RadioGroup) so labels stay visually consistent
-// regardless of whether the input is a fluent web component or a custom one.
+// Canonical FIELD label — bold, block, sits ABOVE a stacked input
+// (TextField, Select, Combobox, Autocomplete, NumberField, Textarea, Slider,
+// DatePicker, TimePicker, RadioGroup, and Checkbox/Switch when labelPosition="top").
 .fluent-label {
 	display: block;
 	font-size: 0.875rem;
@@ -44,3 +44,23 @@
 	margin-bottom: 0.25rem;
 }
 
+// Canonical VALUE label — inline, normal weight, pointer cursor.
+// Used for the text that sits next to a control and describes the value/option
+// itself (Checkbox/Switch inline labels in labelPosition="start"/"end"). The
+// pointer cursor is the sole hover affordance — no color shift, matching how
+// fluent-radio's slotted default-slot label behaves natively.
+.fluent-value-label {
+	display: inline;
+	font-size: 0.875rem;
+	font-weight: normal;
+	line-height: 1.25;
+	color: var(--neutral-foreground-rest);
+	cursor: pointer;
+	user-select: none;
+}
+// Disabled / readonly host swaps the cursor to indicate non-interactivity.
+[data-disabled="true"] > .fluent-value-label,
+[data-readonly="true"] > .fluent-value-label {
+	cursor: not-allowed;
+}
+

package/dist/components/Checkbox.svelte

@@ -56,6 +56,16 @@
 		onclick = undefined
 	}: Props = $props()
 
+	// Stable fallback id so <label for={...}> always links to the checkbox —
+	// without it, clicking the value label on an id-less <Checkbox /> wouldn't
+	// toggle the box.
+	const fallbackId = `fluent-checkbox-${Math.random().toString(36).slice(2, 11)}`
+	const effectiveId = $derived(id ?? fallbackId)
+
+	// Checkbox label always describes the value next to the control — never a
+	// field-label — so styling stays the same across all positions; only the
+	// wrapper's flex direction changes per labelPosition.
+
 	const currentMessage = $derived(
 		checked === true ? checkedMessage
 			: checked === false ? uncheckedMessage
@@ -126,9 +136,14 @@
 	}
 </script>
 
-<span class="fluent-checkbox-wrapper" data-label-position={labelPosition}>
+<span
+	class="fluent-checkbox-wrapper"
+	data-label-position={labelPosition}
+	data-disabled={disabled ? "true" : null}
+	data-readonly={readonly ? "true" : null}
+>
 	{#if label || labelTemplate || children}
-		<label for={id} class="fluent-label">
+		<label for={effectiveId} class="fluent-value-label">
 			{#if label}{label}{/if}
 			{#if labelTemplate}{@render labelTemplate?.()}{/if}
 			{#if children}{@render children?.()}{/if}
@@ -146,7 +161,7 @@
 		{readonly}
 		{disabled}
 		{required}
-		{id}
+		id={effectiveId}
 		{name}
 		aria-label={ariaLabel || label || null}
 		class={className || null}
@@ -176,17 +191,8 @@
 		gap: 0.5rem;
 	}
 
-	/* `.fluent-label` carries a 0.25rem bottom margin (set globally in
-	   components.scss for stacked form-field labels). In inline layouts that
-	   margin extends the label's flex-item box downward, so `align-items:
-	   center` lifts the label's visible text above the checkbox midline. Zero
-	   it out for start/end; keep it for top where the bottom margin is the
-	   intended gap before the control. */
-	.fluent-checkbox-wrapper[data-label-position="start"] .fluent-label,
-	.fluent-checkbox-wrapper[data-label-position="end"] .fluent-label {
-		margin-bottom: 0;
-	}
-
+	/* "top" position: label stacks above the checkbox. Label keeps its
+	   value-label styling — only the wrapper layout changes. */
 	.fluent-checkbox-wrapper[data-label-position="top"] {
 		flex-direction: column;
 		align-items: flex-start;
@@ -200,7 +206,7 @@
 	   We use the `order` property rather than `flex-direction: row-reverse`
 	   so the optional status message always trails the [checkbox, label] pair
 	   instead of jumping to the front (which row-reverse would do). */
-	.fluent-checkbox-wrapper[data-label-position="end"] .fluent-label {
+	.fluent-checkbox-wrapper[data-label-position="end"] :global(.fluent-value-label) {
 		order: 1;
 	}
 	.fluent-checkbox-wrapper[data-label-position="end"] .checkbox-message {

package/dist/components/Combobox.svelte

@@ -239,7 +239,7 @@
 
 <!-- svelte-ignore a11y_label_has_associated_control -->
 {#if label || labelTemplate}
-	<label class="combobox-label">
+	<label class="fluent-label" for={id}>
 		{#if label}
 			{label}
 		{/if}
@@ -282,14 +282,6 @@
 </fluent-combobox>
 
 <style>
-	.combobox-label {
-		display: block;
-		font-size: 0.875rem;
-		font-weight: 600;
-		color: var(--neutral-foreground-rest);
-		margin-bottom: 0.25rem;
-	}
-
 	.required-indicator {
 		color: var(--error-foreground-rest, #d13438);
 		margin-left: 0.25rem;

package/dist/components/Divider.svelte

@@ -8,9 +8,11 @@
 	type Props = {
 		class?: string
 		style?: string
+		orientation?: "horizontal" | "vertical"
+		role?: "separator" | "presentation"
 	}
 
-	let {class: className = "", style = ""}: Props = $props()
+	let {class: className = "", style = "", orientation = "horizontal", role = "separator"}: Props = $props()
 </script>
 
 <!-- fluent-divider's shadow DOM borders itself with `--neutral-stroke-divider-rest`
@@ -18,5 +20,10 @@
      page background and reads as invisible. Re-point the token at the heavier
      `--neutral-stroke-rest` so the line actually shows up. The variable is
      inherited into the shadow DOM, so setting it on the host suffices. -->
-<fluent-divider class={className} style="--neutral-stroke-divider-rest: var(--neutral-stroke-rest); {style}"></fluent-divider>
+<fluent-divider
+	class={className}
+	{orientation}
+	{role}
+	style="--neutral-stroke-divider-rest: var(--neutral-stroke-rest); {style}"
+></fluent-divider>
 

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

@@ -1,6 +1,8 @@
 type Props = {
     class?: string;
     style?: string;
+    orientation?: "horizontal" | "vertical";
+    role?: "separator" | "presentation";
 };
 declare const Divider: import("svelte").Component<Props, {}, "">;
 type Divider = ReturnType<typeof Divider>;

package/dist/components/PositioningRegion.svelte

@@ -28,6 +28,12 @@
 		 * width via Floating UI's `size` middleware. Useful for dropdowns whose
 		 * options should align under the input. */
 		matchWidth?: boolean
+		/** When true, exposes the remaining viewport height as the CSS custom
+		 * property `--available-height` on the floating element (minus the
+		 * shift padding). Consumers should set max-height: var(--available-height)
+		 * on a scroll container inside, so the dropdown stays inside the viewport
+		 * regardless of which side flip() picks. */
+		availableHeight?: boolean
 		children?: SlotType
 	}
 
@@ -39,6 +45,7 @@
 		position: positionProp = "bottom",
 		align: alignProp = "center",
 		matchWidth = true,
+		availableHeight = false,
 		children = undefined
 	}: Props = $props()
 
@@ -60,10 +67,12 @@
 		anchor: HTMLElement
 		placement: Placement
 		matchWidth: boolean
+		availableHeight: boolean
 	}
 
 	function position(node: HTMLElement, params: PositionParams) {
 		let cleanup: () => void = () => {}
+		const SHIFT_PADDING = 8
 
 		function attach(p: PositionParams) {
 			cleanup()
@@ -71,13 +80,22 @@
 				const middleware = [
 					offset(0),
 					flip(),
-					shift({padding: 8})
+					shift({padding: SHIFT_PADDING})
 				]
-				if (p.matchWidth) {
+				if (p.matchWidth || p.availableHeight) {
 					middleware.push(
 						size({
-							apply({rects, elements}) {
-								elements.floating.style.width = `${rects.reference.width}px`
+							padding: SHIFT_PADDING,
+							apply({rects, elements, availableHeight: h}) {
+								if (p.matchWidth) {
+									elements.floating.style.width = `${rects.reference.width}px`
+								}
+								if (p.availableHeight) {
+									elements.floating.style.setProperty(
+										"--available-height",
+										`${Math.max(0, Math.floor(h))}px`
+									)
+								}
 							}
 						})
 					)
@@ -110,7 +128,7 @@
 	{#if visible}
 		<div
 			use:portal
-			use:position={{anchor, placement, matchWidth}}
+			use:position={{anchor, placement, matchWidth, availableHeight}}
 			class="positioning-region positioning-region-floating"
 			{title}
 			style="position: fixed; top: 0; left: 0; {style}"

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

@@ -15,6 +15,12 @@ type Props = {
      * width via Floating UI's `size` middleware. Useful for dropdowns whose
      * options should align under the input. */
     matchWidth?: boolean;
+    /** When true, exposes the remaining viewport height as the CSS custom
+     * property `--available-height` on the floating element (minus the
+     * shift padding). Consumers should set max-height: var(--available-height)
+     * on a scroll container inside, so the dropdown stays inside the viewport
+     * regardless of which side flip() picks. */
+    availableHeight?: boolean;
     children?: SlotType;
 };
 declare const PositioningRegion: import("svelte").Component<Props, {}, "">;