fluentui-svelte 0.6.0 → 0.7.0

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

@@ -6,12 +6,14 @@ A Label provides an accessible caption for a form control. It supports different
 
 ```svelte
 <script>
-	import { Label } from 'fluentui-svelte';
+	import { Label, TextBox } from 'fluentui-svelte';
 </script>
 
-<Label label="Email" />
+<Label label="Email"><TextBox /></Label>
 ```
 
+The root is a `div` by default; `as="span"` selects a span. The text label and the field are siblings. Label is for the first field inside it, which takes the id of the label when it has none of its own; pass `for` to point the label at another field. Inside a Label, the own text of a Checkbox, RadioButton or ToggleSwitch is not rendered: the Label names the control. `size` and `weight` style only the label text. `class`, other label attributes and `ref` apply to the label; use `wrapperAttributes` and `wrapperRef` for the root.
+
 ## Examples
 
 ### Size
@@ -19,9 +21,9 @@ A Label provides an accessible caption for a form control. It supports different
 Use the `size` prop to control the label text size.
 
 ```svelte
-<Label size="small" label="Small" />
-<Label size="medium" label="Medium" />
-<Label size="large" label="Large" />
+<Label size="small" label="Small"><TextBox /></Label>
+<Label size="medium" label="Medium"><TextBox /></Label>
+<Label size="large" label="Large"><TextBox /></Label>
 ```
 
 ### Weight
@@ -29,8 +31,8 @@ Use the `size` prop to control the label text size.
 Use the `weight` prop to switch between a regular and a semibold label.
 
 ```svelte
-<Label weight="regular" label="Regular" />
-<Label weight="semibold" label="Semibold" />
+<Label weight="regular" label="Regular"><TextBox /></Label>
+<Label weight="semibold" label="Semibold"><TextBox /></Label>
 ```
 
 ### Label Position
@@ -38,10 +40,10 @@ Use the `weight` prop to switch between a regular and a semibold label.
 Use the `labelPosition` prop to place the label text relative to the wrapped control.
 
 ```svelte
-<Label labelPosition="before" label="Before" />
-<Label labelPosition="after" label="After" />
-<Label labelPosition="above" label="Above" />
-<Label labelPosition="below" label="Below" />
+<Label labelPosition="before" label="Before"><TextBox /></Label>
+<Label labelPosition="after" label="After"><TextBox /></Label>
+<Label labelPosition="above" label="Above"><TextBox /></Label>
+<Label labelPosition="below" label="Below"><TextBox /></Label>
 ```
 
 ### Required
@@ -49,23 +51,74 @@ Use the `labelPosition` prop to place the label text relative to the wrapped con
 Pass a `required` object to mark the label as required and render a required indicator.
 
 ```svelte
-<Label label="Email" required={{ message: 'Required field' }} />
+<Label label="Email" required={{ message: 'Required field' }}><TextBox required /></Label>
+```
+
+### Tooltip
+
+Pass `tooltipContent`, as text, a snippet or a component, to show more about the field in a tooltip from a badge after the label text. The badge is a button named after the label; `tooltipBadge` replaces its info icon, and `tooltipButtonAttributes` its `aria-label`. Keep links and buttons out of the tooltip.
+
+```svelte
+<Label
+	label="Bank"
+	labelPosition="above"
+	required={{ message: 'Required field' }}
+	tooltipContent="The bank that holds the account the payments come from."
+>
+	<Dropdown placeholder="Bank Name">
+		<DropdownOption value="pichincha">Banco Pichincha</DropdownOption>
+		<DropdownOption value="guayaquil">Banco Guayaquil</DropdownOption>
+	</Dropdown>
+</Label>
+<Label
+	label="IBAN"
+	labelPosition="above"
+	tooltipBadge={QuestionCircleRegular}
+	tooltipContent="The international number of the account, as your bank prints it."
+>
+	<TextBox placeholder="EC00 0000 0000 0000" />
+</Label>
 ```
 
+### Other form controls
+
+```svelte
+<Label label="Accept terms"><Checkbox /></Label>
+<Label label="Email updates"><ToggleSwitch /></Label>
+<Label label="Standard plan"><RadioButton name="plan" value="standard" /></Label>
+<Label label="Country">
+	<Dropdown><DropdownOption value="bo">Bolivia</DropdownOption></Dropdown>
+</Label>
+```
+
+Label renders its text and field as siblings, and is for the first field inside it, which takes the id of the label when it has none of its own. Pass for to point the label at another field. HTML attributes, class and ref apply to the label text element; wrapperAttributes and wrapperRef apply to the container. Size and weight affect only the label text.
+
+A control inside Label needs no id or for. The own text of a Checkbox, RadioButton or ToggleSwitch inside it is not rendered: the Label names the control. A native `<label for>` outside a Label names a picker (Dropdown, TagPicker, DatePicker, TimePicker, CalendarDatePicker) only once the page hydrates, because the picker reads it from the page: when rendering on the server, use Label or pass `aria-labelledby`. A field with an id of its own keeps it: when the text comes before the field (`labelPosition` `'before'` or `'above'`, the default), pass that id to `for` too, or the label the server writes points at no field until the page hydrates.
+
 ## Component Props
 
 <!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
 <!-- props:LabelProps -->
 
-| Name                         | Type                                                          | Default           | Description                                                               |
-| ---------------------------- | ------------------------------------------------------------- | ----------------- | ------------------------------------------------------------------------- |
-| `label`                      | `string`                                                      | `'Label Element'` | The text of the label. Falls back to the rendered children.               |
-| `size`                       | `'small'` &#124; `'medium'` &#124; `'large'`                  | `'medium'`        | The size of the label text.                                               |
-| `weight`                     | `'regular'` &#124; `'semibold'`                               | `'regular'`       | The weight of the label text.                                             |
-| `labelPosition`              | `'before'` &#124; `'after'` &#124; `'above'` &#124; `'below'` | `'after'`         | Where the label sits relative to the field it describes.                  |
-| `required`                   | `{ abbr?: string; message: string; }`                         |                   | Marks the field as required, and describes why through the given message. |
-| `disabled`                   | `boolean`                                                     |                   | Renders the label as disabled, to match the field it describes.           |
-| `ref` _bindable_             | `HTMLLabelElement`                                            |                   | The DOM reference of the label element.                                   |
-| Element Attributes (`label`) |                                                               |                   |                                                                           |
+| Name                                | Type                                                          | Default            | Description                                                                                                                                                                                                                                                                                         |
+| ----------------------------------- | ------------------------------------------------------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `as`                                | `'div'` &#124; `'span'`                                       | `'div'`            | The element used to wrap the label and its field.                                                                                                                                                                                                                                                   |
+| `children`                          | `Snippet`                                                     |                    | The field described by the label, rendered beside the label text.                                                                                                                                                                                                                                   |
+| `wrapperRef` _bindable_             | `HTMLDivElement` &#124; `HTMLSpanElement`                     |                    | The DOM reference of the wrapper element.                                                                                                                                                                                                                                                           |
+| `wrapperAttributes`                 | `HTMLAttributes`                                              |                    | The attributes to spread on the wrapper element.                                                                                                                                                                                                                                                    |
+| `label`                             | `string`                                                      | `'Label Element'`  | The text of the label.                                                                                                                                                                                                                                                                              |
+| `size`                              | `'small'` &#124; `'medium'` &#124; `'large'`                  | `'medium'`         | The size of the label text.                                                                                                                                                                                                                                                                         |
+| `weight`                            | `'regular'` &#124; `'semibold'`                               | `'regular'`        | The weight of the label text.                                                                                                                                                                                                                                                                       |
+| `labelPosition`                     | `'before'` &#124; `'after'` &#124; `'above'` &#124; `'below'` | `'after'`          | Where the label sits relative to the field it describes.                                                                                                                                                                                                                                            |
+| `required`                          | `{ abbr?: string; message: string; }`                         |                    | Marks the field as required, and describes why through the given message.                                                                                                                                                                                                                           |
+| `disabled`                          | `boolean`                                                     |                    | Renders the label as disabled, to match the field it describes.                                                                                                                                                                                                                                     |
+| `ref` _bindable_                    | `HTMLLabelElement` &#124; `null`                              |                    | The DOM reference of the label element.                                                                                                                                                                                                                                                             |
+| `id`                                | `string`                                                      | `Generated`        | The id of the label element. A control inside the label is named after it, including a picker whose visible control stands in for its native field.                                                                                                                                                 |
+| `for`                               | `string`                                                      | `The field inside` | The id of the field the label is for. Without it, the label is for the first field inside it, which takes a generated id when it has none of its own. With `labelPosition` `before` or `above` and a field that has an id of its own, pass that id here, so the server renders the association too. |
+| `tooltipContent`                    | `string` &#124; `Snippet` &#124; `Component`                  |                    | More about the field, in a tooltip shown from a badge after the label text, on hover and on focus. People cannot move into a tooltip, so keep links and buttons out of it.                                                                                                                          |
+| `tooltipBadge`                      | `Snippet` &#124; `Component`                                  | `InfoRegular`      | What the badge that shows the tooltip displays. Only rendered with `tooltipContent`.                                                                                                                                                                                                                |
+| `tooltipProps`                      | `TooltipProps`                                                |                    | The props to spread on the tooltip.                                                                                                                                                                                                                                                                 |
+| `tooltipButtonAttributes`           | `HTMLButtonAttributes`                                        |                    | The attributes to spread on the button of the badge. Its name is the label text followed by its `aria-label`.                                                                                                                                                                                       |
+| `HTMLLabelAttributes` without `for` |                                                               |                    |                                                                                                                                                                                                                                                                                                     |
 
 <!-- /props:LabelProps -->

package/dist/components/label/label-context.d.ts

@@ -0,0 +1,14 @@
+export type LabelContext = {
+    /** The id of the label text, which names a visible control that stands in for a native field. */
+    readonly labelId: string;
+    /** The id the label is for: a field with no id of its own takes it. */
+    readonly fieldId: string;
+    /** Makes a field, through the id it reports, the one the label is for. Only the first field to ask gets it. */
+    claim: (id: () => string | null | undefined) => boolean;
+};
+export declare const getLabelContext: () => LabelContext | null, setLabelContext: (context: LabelContext) => void;
+/**
+ * The Label a field is inside, when the field is the first one there to claim it: the label is then
+ * for that field. Outside a Label, and for any later field, it is `null`, and the field works on its own.
+ */
+export declare function claimLabel(id: () => string | null | undefined): Omit<LabelContext, 'claim'> | null;

package/dist/components/label/label-context.js

@@ -0,0 +1,10 @@
+import { createFSContext } from '../../internal/index.js';
+export const [getLabelContext, setLabelContext] = createFSContext();
+/**
+ * The Label a field is inside, when the field is the first one there to claim it: the label is then
+ * for that field. Outside a Label, and for any later field, it is `null`, and the field works on its own.
+ */
+export function claimLabel(id) {
+    const label = getLabelContext();
+    return label?.claim(id) ? label : null;
+}

package/dist/components/label/label.svelte

@@ -1,52 +1,129 @@
 <script lang="ts">
+	import InfoRegular from 'fluentui-icons-svelte/InfoRegular.svelte';
+	import type { Attachment } from 'svelte/attachments';
 	import type { LabelProps } from './types.js';
+	import { PREFIX } from '../../internal/constants.js';
+	import { RenderSoC } from '../../internal/index.js';
+	import { Tooltip } from '../../index.js';
+	import { setLabelContext } from './label-context.js';
+
+	const FALLBACK_ID = $props.id();
 
 	let {
-		ref = $bindable(),
+		id = `${PREFIX}-label-${FALLBACK_ID}`,
+		for: htmlFor,
+		ref = $bindable(null),
+		as = 'div',
+		wrapperRef = $bindable(null),
+		wrapperAttributes,
 		class: classes,
 		disabled,
 		required,
 		size = 'medium',
 		weight = 'regular',
 		label = 'Label Element',
-		labelPosition = 'after',
+		labelPosition = 'above',
+		tooltipContent,
+		tooltipBadge = InfoRegular,
+		tooltipProps,
+		tooltipButtonAttributes,
 		children,
 		...attributes
 	}: LabelProps = $props();
+
+	/** The field inside the label, used to get its id */
+	let field = $state<() => string | null | undefined>();
+
+	const fieldId = $derived(htmlFor ?? `${id}-field`);
+
+	const INFO_ID = $derived(tooltipButtonAttributes?.id ?? `${id}-info`);
+
+	setLabelContext({
+		get labelId() {
+			return id;
+		},
+		get fieldId() {
+			return fieldId;
+		},
+		claim(report) {
+			if (field) return false;
+			field = report;
+			return true;
+		}
+	});
 </script>
 
-<label
+<svelte:element
+	this={as}
+	{...wrapperAttributes}
 	class={[
 		'fs-label',
 		`size-${size}`,
-		`weight-${weight}`,
-		classes,
 		{ disabled, required },
-		(labelPosition === 'above' || labelPosition === 'below') && 'column'
+		(labelPosition === 'above' || labelPosition === 'below') && 'column',
+		wrapperAttributes?.class
 	]}
-	bind:this={ref}
-	{...attributes}
+	bind:this={wrapperRef}
 >
 	{#if labelPosition === 'before' || labelPosition === 'above'}
-		<span>
-			{label}
-			{#if required}
-				<abbr title={required.message || label}>{required.abbr ?? '*'}</abbr>
-			{/if}
-		</span>
+		{@render labelText()}
 	{/if}
 
 	{@render children?.()}
 
 	{#if labelPosition === 'after' || labelPosition === 'below'}
-		<span>
-			{label}
-			{#if required}
-				<abbr title={required.message || label}>{required.abbr ?? '*'}</abbr>
-			{/if}
+		{@render labelText()}
+	{/if}
+</svelte:element>
+
+{#snippet labelText()}
+	{#if tooltipContent}
+		<!-- The badge sits beside the label text, not in it, or its name would join the name of the field. -->
+		<span class={['fs-label-heading', `size-${size}`]}>
+			{@render text()}
+			<Tooltip
+				withArrow
+				placement="top"
+				{...tooltipProps}
+				content={tooltipContent}
+				relationship="description"
+				children={badge}
+			/>
 		</span>
+	{:else}
+		{@render text()}
 	{/if}
-</label>
+{/snippet}
+
+{#snippet badge(attrs: { 'aria-describedby'?: string }, attach: Attachment)}
+	<button
+		type="button"
+		aria-label="More information"
+		{...tooltipButtonAttributes}
+		{...attrs}
+		id={INFO_ID}
+		aria-labelledby={tooltipButtonAttributes?.['aria-labelledby'] ?? `${id} ${INFO_ID}`}
+		class={['fs-label-info', tooltipButtonAttributes?.class]}
+		{@attach attach}
+	>
+		<RenderSoC SoC={tooltipBadge} />
+	</button>
+{/snippet}
+
+{#snippet text()}
+	<label
+		{...attributes}
+		{id}
+		for={field ? field() : fieldId}
+		class={['fs-label-text', `size-${size}`, `weight-${weight}`, classes]}
+		bind:this={ref}
+	>
+		{label}
+		{#if required}
+			<abbr aria-hidden="true" title={required.message || label}>{required.abbr ?? '*'}</abbr>
+		{/if}
+	</label>
+{/snippet}
 
 <style>
 	.fs-label {
@@ -58,24 +135,14 @@
 			align-items: flex-start;
 		}
 		&.size-small {
-			font-size: var(--fs-caption-font-size);
-			letter-spacing: 0.04em;
 			gap: 0.25rem;
 		}
 		&.size-medium {
-			font-size: var(--fs-body-font-size);
 			gap: 0.375rem;
 		}
 		&.size-large {
-			font-size: var(--fs-subtitle2-font-size);
 			gap: 0.5rem;
 		}
-		&.weight-regular {
-			font-weight: 400;
-		}
-		&.weight-semibold {
-			font-weight: 600;
-		}
 		&.disabled {
 			color: var(--fs-text-disabled);
 			pointer-events: none;
@@ -91,5 +158,61 @@
 				color: var(--fs-text-disabled);
 			}
 		}
+		& .fs-label-heading {
+			display: inline-flex;
+			align-items: center;
+			gap: 0.25rem;
+			&.size-small .fs-label-info {
+				font-size: 0.75rem;
+			}
+			&.size-large .fs-label-info {
+				font-size: 1.25rem;
+			}
+		}
+		& .fs-label-info {
+			display: inline-flex;
+			align-items: center;
+			padding: 0;
+			border: none;
+			border-radius: var(--fs-control-border-radius);
+			background: none;
+			color: var(--fs-text-secondary);
+			font-size: 1rem;
+			cursor: pointer;
+			&:hover {
+				color: var(--fs-text-primary);
+			}
+			&:focus-visible {
+				outline: 0.125rem var(--fs-focus-stroke-outer) solid;
+				outline-offset: 0.063rem;
+			}
+			& :global(svg) {
+				inline-size: 1em;
+				block-size: 1em;
+			}
+		}
+		& .fs-label-text {
+			&.size-small {
+				font-size: var(--fs-caption-font-size);
+				letter-spacing: 0.04em;
+			}
+			&.size-medium {
+				font-size: var(--fs-body-font-size);
+			}
+			&.size-large {
+				font-size: var(--fs-subtitle2-font-size);
+			}
+			&.weight-regular {
+				font-weight: 400;
+			}
+			&.weight-semibold {
+				font-weight: 600;
+			}
+		}
+		&:global(:has(*:user-invalid)) {
+			& .fs-label-text {
+				color: var(--fs-system-critical);
+			}
+		}
 	}
 </style>

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

@@ -1,4 +1,4 @@
 import type { LabelProps } from './types.ts';
-declare const Label: import("svelte").Component<LabelProps, {}, "ref">;
+declare const Label: import("svelte").Component<LabelProps, {}, "ref" | "wrapperRef">;
 type Label = ReturnType<typeof Label>;
 export default Label;

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

@@ -1,8 +1,27 @@
-import type { HTMLLabelAttributes } from 'svelte/elements';
+import type { Component, Snippet } from 'svelte';
+import type { HTMLAttributes, HTMLButtonAttributes, HTMLLabelAttributes } from 'svelte/elements';
 import type { Sizes } from '../../types/index.js';
+import type { TooltipProps } from '../tooltip/types.ts';
 /** @propsmith LabelProps */
 export type LabelProps = {
-    /** The text of the label. Falls back to the rendered children.
+    /** The element used to wrap the label and its field.
+     * @default 'div'
+     */
+    as?: 'div' | 'span';
+    /** The field described by the label, rendered beside the label text.
+     * @type Snippet
+     */
+    children?: Snippet;
+    /** The DOM reference of the wrapper element.
+     * @type HTMLDivElement | HTMLSpanElement
+     * @bindable
+     */
+    wrapperRef?: HTMLDivElement | HTMLSpanElement | null;
+    /** The attributes to spread on the wrapper element.
+     * @type HTMLAttributes
+     */
+    wrapperAttributes?: HTMLAttributes<HTMLDivElement | HTMLSpanElement>;
+    /** The text of the label.
      * @default 'Label Element'
      */
     label?: string;
@@ -28,5 +47,30 @@ export type LabelProps = {
     /** The DOM reference of the label element.
      * @bindable
      */
-    ref?: HTMLLabelElement;
-} & HTMLLabelAttributes;
+    ref?: HTMLLabelElement | null;
+    /** The id of the label element. A control inside the label is named after it, including a picker whose visible control stands in for its native field.
+     * @default Generated
+     */
+    id?: string;
+    /** The id of the field the label is for. Without it, the label is for the first field inside it, which takes a generated id when it has none of its own. With `labelPosition` `before` or `above` and a field that has an id of its own, pass that id here, so the server renders the association too.
+     * @default The field inside
+     */
+    for?: string;
+    /** More about the field, in a tooltip shown from a badge after the label text, on hover and on focus. People cannot move into a tooltip, so keep links and buttons out of it.
+     * @type string | Snippet | Component
+     */
+    tooltipContent?: string | Snippet | Component;
+    /** What the badge that shows the tooltip displays. Only rendered with `tooltipContent`.
+     * @type Snippet | Component
+     * @default InfoRegular
+     */
+    tooltipBadge?: Snippet | Component;
+    /** The props to spread on the tooltip.
+     * @type TooltipProps
+     */
+    tooltipProps?: Omit<TooltipProps, 'content' | 'relationship' | 'children'>;
+    /** The attributes to spread on the button of the badge. Its name is the label text followed by its `aria-label`.
+     * @type HTMLButtonAttributes
+     */
+    tooltipButtonAttributes?: HTMLButtonAttributes;
+} & Omit<HTMLLabelAttributes, 'for'>;