fluentui-svelte 0.4.0 → 0.6.0

package/dist/components/menu/docs/llms.md

@@ -140,6 +140,22 @@ This variant of the `MenuTrigger` component allows you to create context menus t
 
 <!-- /props:MenuProps -->
 
+## Component Props (MenuPopover)
+
+<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
+<!-- props:MenuPopoverProps -->
+
+| Name              | Type                                 | Default | Description                                              |
+| ----------------- | ------------------------------------ | ------- | -------------------------------------------------------- |
+| `ref`             | `HTMLElement`                        |         | The element used to position the popover.                |
+| `open` _bindable_ | `boolean`                            |         | Controls the open state of the popover.                  |
+| `keepMounted`     | `boolean`                            | `false` | Keeps the popover mounted in the DOM while it is closed. |
+| `placement`       | `ComputePositionConfig['placement']` |         | Where the popover is positioned relative to its trigger. |
+| `positionConfig`  | `ComputePositionConfig`              |         | The position configuration handed over to floating-ui.   |
+| `children`        | `Snippet`                            |         | The content of the popover.                              |
+
+<!-- /props:MenuPopoverProps -->
+
 ## Component Props (MenuTrigger)
 
 <!-- DO NOT EDIT THIS SECTION (propsmith generated) -->

package/dist/components/menu/menu-popover.svelte

@@ -6,12 +6,12 @@
 	import { useDebounce } from 'runed';
 	import { floating, flyToOffset, getCSSDuration, reactiveBoundingRect } from '../../internal/index.js';
 	import { getReducedMotion } from '../../providers/fluentui-svelte/fluentui-svelte.js';
-	import type { Snippet } from 'svelte';
-	import type { ComputePositionConfig } from '@floating-ui/dom';
+	import type { MenuPopoverProps } from './types.js';
 
 	let {
 		ref: _ref,
 		open: _open = $bindable(),
+		keepMounted = false,
 		placement,
 		positionConfig: floatingPosition = {
 			placement,
@@ -19,13 +19,7 @@
 			strategy: 'fixed'
 		},
 		children
-	}: {
-		ref?: HTMLElement;
-		open?: boolean;
-		placement?: ComputePositionConfig['placement'];
-		positionConfig?: Partial<ComputePositionConfig>;
-		children: Snippet;
-	} = $props();
+	}: MenuPopoverProps = $props();
 
 	const context = getMenuContext();
 
@@ -90,16 +84,17 @@
 	});
 </script>
 
-{#if opened && ref}
+{#if keepMounted || (opened && ref)}
 	{@const isRefAnElement = ref instanceof HTMLElement}
 	<!-- svelte-ignore a11y_no_static_element_interactions -->
 	<div
 		bind:this={element}
 		class="fs-menu-popover"
+		hidden={!opened}
 		onmouseleave={openOnHover ? (e: MouseEvent) => debounced(e) : undefined}
-		{@attach ref ? floating(ref, config) : undefined}
+		{@attach opened && ref ? floating(ref, config) : undefined}
 		style={`--position=${isSubMenu ? 'absolute' : 'fixed'} --min-width=${isRefAnElement && !isSubMenu ? `${boundingElement.rect.width}px` : 'max-content'}`}
-		in:flyToOffset={isRefAnElement
+		in:flyToOffset={opened && isRefAnElement
 			? {
 					...getIntroTransition({ config, anchor: boundingElement.rect, element, ref, isSubMenu }),
 					duration: duration,

package/dist/components/menu/menu-popover.svelte.d.ts

@@ -1,12 +1,4 @@
-import type { Snippet } from 'svelte';
-import type { ComputePositionConfig } from '@floating-ui/dom';
-type $$ComponentProps = {
-    ref?: HTMLElement;
-    open?: boolean;
-    placement?: ComputePositionConfig['placement'];
-    positionConfig?: Partial<ComputePositionConfig>;
-    children: Snippet;
-};
-declare const MenuPopover: import("svelte").Component<$$ComponentProps, {}, "open">;
+import type { MenuPopoverProps } from './types.ts';
+declare const MenuPopover: import("svelte").Component<MenuPopoverProps, {}, "open">;
 type MenuPopover = ReturnType<typeof MenuPopover>;
 export default MenuPopover;

package/dist/components/menu/types.d.ts

@@ -59,6 +59,27 @@ export type MenuProps = {
     /** The parts of the menu: a trigger and a popover. */
     children?: Snippet;
 };
+/** @propsmith MenuPopoverProps */
+export type MenuPopoverProps = {
+    /** The element used to position the popover. */
+    ref?: HTMLElement;
+    /** Controls the open state of the popover.
+     * @bindable
+     */
+    open?: boolean;
+    /** Keeps the popover mounted in the DOM while it is closed.
+     * @default false
+     */
+    keepMounted?: boolean;
+    /** Where the popover is positioned relative to its trigger. */
+    placement?: ComputePositionConfig['placement'];
+    /** The position configuration handed over to floating-ui.
+     * @type ComputePositionConfig
+     */
+    positionConfig?: Partial<ComputePositionConfig>;
+    /** The content of the popover. */
+    children: Snippet;
+};
 /** @propsmith MenuTriggerProps */
 export type MenuTriggerProps = {
     /** Disables the user interaction. */

package/dist/components/rating/docs/llms.md

@@ -0,0 +1,110 @@
+# Rating
+
+A rating lets users give a value to an item by selecting one of a row of stars. It supports half-filled stars, four sizes and a custom number of items.
+
+## Usage
+
+```svelte
+<script>
+	import { Rating } from 'fluentui-svelte';
+
+	let value = $state(3);
+</script>
+
+<Rating bind:value />
+```
+
+## Component API
+
+A rating lets users give a value to an item, using a row of symbols such as stars. It supports half-filled items and four sizes.
+
+## Examples
+
+### Bind the value
+
+Use `bind:value` to read the rating the user picks.
+
+```svelte
+<script>
+	let value = $state(3);
+</script>
+
+<Rating bind:value />
+```
+
+### Half stars
+
+Set `step={0.5}` to let users pick half-filled stars.
+
+```svelte
+<Rating value={2.5} step={0.5} />
+```
+
+### Quarter stars
+
+Until the user rates, a fractional `value` is drawn in quarters, which is handy to show an average. Once the user picks a star, the rating snaps to the `step`.
+
+```svelte
+<Rating value={3.75} />
+```
+
+### Size
+
+Use `size` to choose between `small`, `medium`, `large` and `extra-large`.
+
+```svelte
+<Rating value={3} size="small" />
+<Rating value={3} size="medium" />
+<Rating value={3} size="large" />
+<Rating value={3} size="extra-large" />
+```
+
+### Shape
+
+Use `iconFilled` and `iconOutline` to replace the stars with any other icon component. Both fall back to the star when omitted, and partially filled items are clipped, so custom shapes also work with `step={0.5}`.
+
+```svelte
+<script>
+	import { HeartFilled, HeartRegular } from 'fluentui-icons-svelte';
+</script>
+
+<Rating value={3} iconFilled={HeartFilled} iconOutline={HeartRegular} />
+```
+
+### Max
+
+Use `max` to change the number of stars.
+
+```svelte
+<Rating value={4} max={10} />
+```
+
+### Item label
+
+Use `itemLabel` to customize the accessible label of each radio input.
+
+```svelte
+<Rating value={3} itemLabel={(rating) => `${rating} out of 5 stars`} />
+```
+
+## Component Props
+
+<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
+<!-- props:RatingProps -->
+
+| Name                                                | Type                                                                | Default                       | Description                                                                                                                   |
+| --------------------------------------------------- | ------------------------------------------------------------------- | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
+| `value` _bindable_                                  | `number`                                                            | `0`                           | The current rating. Fractions are drawn in quarters until the user rates.                                                     |
+| `max`                                               | `number`                                                            | `5`                           | The number of items displayed. Must be a whole number greater than 1.                                                         |
+| `step`                                              | `1` &#124; `0.5`                                                    | `1`                           | The precision of the rating. `0.5` allows half-filled items.                                                                  |
+| `size`                                              | `'small'` &#124; `'medium'` &#124; `'large'` &#124; `'extra-large'` | `'extra-large'`               | The size of the rating items.                                                                                                 |
+| `iconFilled`                                        | `Component`                                                         |                               | The icon of a filled item. Falls back to a filled star. Partially filled items are clipped, so it also works with half steps. |
+| `iconOutline`                                       | `Component`                                                         |                               | The icon of an empty item. Falls back to an outlined star.                                                                    |
+| `name`                                              | `string`                                                            |                               | The name of the radio inputs. Generated when not provided.                                                                    |
+| `itemLabel`                                         | `(rating: number) => string`                                        | `` (rating) => `${rating}` `` | Generates the accessible label of the radio input for a rating value.                                                         |
+| `onChange`                                          | `(value: number) => void`                                           |                               | Called when the user changes the rating.                                                                                      |
+| `class`                                             | `string`                                                            |                               | The class to apply to the rating.                                                                                             |
+| `ref` _bindable_                                    | `HTMLElement`                                                       |                               | The DOM reference of the rating element.                                                                                      |
+| `HTMLAttributes<HTMLDivElement>` without `onchange` |                                                                     |                               |                                                                                                                               |
+
+<!-- /props:RatingProps -->

package/dist/components/rating/rating.svelte

@@ -0,0 +1,210 @@
+<script lang="ts">
+	import { PREFIX } from '../../internal/constants.js';
+	import StarFilled from 'fluentui-icons-svelte/StarFilled.svelte';
+	import StarHalfFilled from 'fluentui-icons-svelte/StarHalfFilled.svelte';
+	import StarOneQuarterFilled from 'fluentui-icons-svelte/StarOneQuarterFilled.svelte';
+	import StarRegular from 'fluentui-icons-svelte/StarRegular.svelte';
+	import StarThreeQuarterFilled from 'fluentui-icons-svelte/StarThreeQuarterFilled.svelte';
+	import type { RatingProps } from './types.js';
+
+	const FALLBACK_ID = $props.id();
+	const COMPONENT_NAME = 'rating';
+	const ID = `${PREFIX}${COMPONENT_NAME}-${FALLBACK_ID}`;
+	const VALUE_ID = `${ID}-value`;
+
+	let {
+		value = $bindable(0),
+		max = 5,
+		step = 1,
+		size = 'extra-large',
+		iconFilled,
+		iconOutline,
+		name = ID,
+		itemLabel = (rating) => `${rating}`,
+		onChange,
+		class: classes,
+		ref = $bindable(),
+		role = 'radiogroup',
+		...attributes
+	}: RatingProps = $props();
+
+	/** Until the user rates, the value is only displayed, so it is drawn with the precision of a quarter. */
+	let rated = $state(false);
+	let hovered = $state<number>();
+
+	const _max = $derived.by(() => {
+		if (!Number.isInteger(max) || max <= 1) throw new Error('Max must be a whole number greater than 1');
+		return max;
+	});
+	const items = $derived(Array.from({ length: _max }, (_, index) => index + 1));
+	const shown = $derived(hovered ?? value);
+	const checkedValue = $derived(value === 0 ? 0 : Math.min(_max, Math.max(step, Math.round(value / step) * step)));
+
+	const custom = $derived(!!(iconFilled || iconOutline));
+
+	/** How much of the item is filled, snapped to the precision it is shown with. */
+	function fillFor(item: number) {
+		const fill = Math.min(Math.max(shown - (item - 1), 0), 1);
+		const precision = hovered !== undefined || rated ? step / 2 : 0.25;
+		return Math.round(fill / precision) * precision;
+	}
+
+	function iconFor(snapped: number) {
+		if (snapped >= 1) return StarFilled;
+		if (snapped >= 0.75) return StarThreeQuarterFilled;
+		if (snapped >= 0.5) return StarHalfFilled;
+		if (snapped >= 0.25) return StarOneQuarterFilled;
+		return StarRegular;
+	}
+
+	function select(next: number) {
+		rated = true;
+		value = next;
+		onChange?.(next);
+	}
+</script>
+
+<!-- 
+	@component
+	A rating lets users give a value to an item, using a row of symbols such as stars. It supports half-filled items and four sizes.
+
+	- Usage:
+	```tsx
+	<script>
+		import { Rating } from 'fluentui-svelte';
+
+		let value = $state(3);
+	</script>
+
+	<Rating bind:value />
+	<Rating bind:value step={0.5} size="medium" />
+	```
+-->
+<div
+	class={['fs-rating', `size-${size}`, classes]}
+	bind:this={ref}
+	{role}
+	onpointerleave={() => (hovered = undefined)}
+	{...attributes}
+	aria-label={attributes['aria-label'] ?? (attributes['aria-labelledby'] ? undefined : 'Rating')}
+	aria-describedby={[attributes['aria-describedby'], VALUE_ID].filter(Boolean).join(' ')}
+>
+	<span id={VALUE_ID} hidden>Current rating: {value} out of {_max}.</span>
+	{#each items as item (item)}
+		{@const fill = fillFor(item)}
+		<span class="rating-item">
+			{#if custom}
+				{@const Outline = iconOutline ?? StarRegular}
+				{@const Filled = iconFilled ?? StarFilled}
+				<span class="rating-icon custom" class:selected={fill > 0} style="--rating-fill: {fill * 100}%">
+					<Outline aria-hidden="true" />
+					<span class="filled"><Filled aria-hidden="true" /></span>
+				</span>
+			{:else}
+				{@const Icon = iconFor(fill)}
+				<span class="rating-icon" class:selected={fill > 0}><Icon aria-hidden="true" /></span>
+			{/if}
+			{#if step === 0.5}
+				<input
+					class="half-value"
+					type="radio"
+					{name}
+					value={item - 0.5}
+					checked={checkedValue === item - 0.5}
+					aria-label={itemLabel(item - 0.5)}
+					onclick={() => value !== item - 0.5 && select(item - 0.5)}
+					onpointerenter={() => (hovered = item - 0.5)}
+				/>
+			{/if}
+			<input
+				class="full-value"
+				type="radio"
+				{name}
+				value={item}
+				checked={checkedValue === item}
+				aria-label={itemLabel(item)}
+				onclick={() => value !== item && select(item)}
+				onpointerenter={() => (hovered = item)}
+			/>
+		</span>
+	{/each}
+</div>
+
+<style>
+	.fs-rating {
+		--rating-size: 24px;
+		display: inline-flex;
+		align-items: center;
+		color: var(--fs-accent-fill-default);
+
+		&.size-small {
+			--rating-size: 12px;
+		}
+
+		&.size-medium {
+			--rating-size: 16px;
+		}
+
+		&.size-large {
+			--rating-size: 20px;
+		}
+	}
+
+	.rating-item {
+		display: inline-flex;
+		position: relative;
+		border-radius: var(--fs-control-border-radius);
+		padding: 2px;
+
+		&:has(input:focus-visible) {
+			box-shadow: var(--fs-focus-stroke-outer);
+		}
+
+		& input {
+			appearance: none;
+			position: absolute;
+			inset-block: 0;
+			inset-inline-start: 0;
+			margin: 0;
+			outline: none;
+			cursor: pointer;
+			inline-size: 100%;
+			block-size: 100%;
+		}
+
+		& .half-value {
+			z-index: 1;
+			inline-size: 50%;
+		}
+	}
+
+	.rating-icon {
+		display: inline-flex;
+		color: var(--fs-text-secondary);
+
+		&.selected {
+			color: var(--fs-accent-fill-default);
+		}
+
+		& :global(svg) {
+			inline-size: var(--rating-size);
+			block-size: var(--rating-size);
+		}
+
+		&.custom {
+			position: relative;
+
+			& .filled {
+				display: inline-flex;
+				position: absolute;
+				inset: 0;
+				color: var(--fs-accent-fill-default);
+				clip-path: inset(0 calc(100% - var(--rating-fill)) 0 0);
+
+				&:dir(rtl) {
+					clip-path: inset(0 0 0 calc(100% - var(--rating-fill)));
+				}
+			}
+		}
+	}
+</style>

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

@@ -0,0 +1,19 @@
+import type { RatingProps } from './types.ts';
+/**
+ * A rating lets users give a value to an item, using a row of symbols such as stars. It supports half-filled items and four sizes.
+ *
+ * - Usage:
+ * ```tsx
+ * <script>
+ * 	import { Rating } from 'fluentui-svelte';
+ *
+ * 	let value = $state(3);
+ * </script>
+ *
+ * <Rating bind:value />
+ * <Rating bind:value step={0.5} size="medium" />
+ * ```
+ */
+declare const Rating: import("svelte").Component<RatingProps, {}, "ref" | "value">;
+type Rating = ReturnType<typeof Rating>;
+export default Rating;

package/dist/components/rating/types.d.ts

@@ -0,0 +1,44 @@
+import type { Component } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+/** @propsmith RatingProps */
+export type RatingProps = {
+    /** The current rating. Fractions are drawn in quarters until the user rates.
+     * @default 0
+     * @bindable
+     */
+    value?: number;
+    /** The number of items displayed. Must be a whole number greater than 1.
+     * @default 5
+     */
+    max?: number;
+    /** The precision of the rating. `0.5` allows half-filled items.
+     * @default 1
+     */
+    step?: 1 | 0.5;
+    /** The size of the rating items.
+     * @default 'extra-large'
+     */
+    size?: 'small' | 'medium' | 'large' | 'extra-large';
+    /** The icon of a filled item. Falls back to a filled star. Partially filled items are clipped, so it also works with half steps.
+     * @type Component
+     */
+    iconFilled?: Component;
+    /** The icon of an empty item. Falls back to an outlined star.
+     * @type Component
+     */
+    iconOutline?: Component;
+    /** The name of the radio inputs. Generated when not provided. */
+    name?: string;
+    /** Generates the accessible label of the radio input for a rating value.
+     * @default (rating) => `${rating}`
+     */
+    itemLabel?: (rating: number) => string;
+    /** Called when the user changes the rating. */
+    onChange?: (value: number) => void;
+    /** The class to apply to the rating. */
+    class?: string;
+    /** The DOM reference of the rating element.
+     * @bindable
+     */
+    ref?: HTMLElement;
+} & Omit<HTMLAttributes<HTMLDivElement>, 'onchange'>;

package/dist/components/rating/types.js

@@ -0,0 +1 @@
+export {};