fluentui-svelte 0.3.0 → 0.4.0

package/dist/components/tab-view/types.d.ts

@@ -0,0 +1,79 @@
+import type { FSContext } from '../../internal/index.js';
+import type { Snippet, Component } from 'svelte';
+import type { HTMLAttributes, HTMLButtonAttributes } from 'svelte/elements';
+/** How every tab of the strip takes its width. */
+export type TabWidthMode = 'equal' | 'size-to-content' | 'compact';
+export type TabViewContext = FSContext<{
+    closable: boolean;
+    tabWidthMode: TabWidthMode;
+}, {
+    activeTab: string;
+}, null, {
+    setActiveTab: (event: Event, value: string) => void;
+    closeTab: (event: Event, value: string) => void;
+}>;
+/** @propsmith TabViewProps */
+export type TabViewProps = {
+    /** The DOM reference of the element wrapping the strip.
+     * @bindable
+     */
+    ref?: HTMLDivElement;
+    /** The DOM reference of the tab list.
+     * @bindable
+     */
+    listRef?: HTMLDivElement;
+    /** The props to spread on the tab list element, where the `tablist` role and its label belong.
+     * @type HTMLAttributes
+     */
+    listProps?: HTMLAttributes<HTMLDivElement>;
+    /** The value of the selected tab.
+     * @bindable
+     */
+    activeTab?: string;
+    /** Fired when the selected tab changes. */
+    onTabChange?: (event: Event, value: string) => void;
+    /** Every tab shows a close button, unless the tab opts out of it.
+     * @default false
+     */
+    closable?: boolean;
+    /** Fired when a tab asks to be closed. Removing the tab is left to the consumer. */
+    onTabClose?: (event: Event, value: string) => void;
+    /** Shows the button that adds a new tab at the end of the strip.
+     * @default false
+     */
+    showNewTabButton?: boolean;
+    /** Fired when the new tab button is activated. */
+    onNewTab?: (event: MouseEvent) => void;
+    /** The props to spread on the new tab button.
+     * @type HTMLButtonAttributes
+     */
+    newTabButtonProps?: HTMLButtonAttributes;
+    /** How the tabs take their width: sharing the strip evenly, sizing to their own content, or
+     * shrinking to the icon of every tab but the selected one.
+     * @default 'equal'
+     */
+    tabWidthMode?: TabWidthMode;
+    /** Opts the strip out of the tabspot focus management, to wire your own.
+     * @default false
+     */
+    disableTabspot?: boolean;
+} & HTMLAttributes<HTMLDivElement>;
+/** @propsmith TabViewTabProps */
+export type TabViewTabProps = {
+    /** The DOM reference of the tab element.
+     * @bindable
+     */
+    ref?: HTMLDivElement;
+    /** The value that identifies the tab. Defaults to a generated id. */
+    value?: string;
+    /** The icon to display before the label.
+     * @type Snippet | Component
+     */
+    icon?: Snippet | Component;
+    /** Shows the close button of the tab. Falls back to the `closable` of the strip. */
+    closable?: boolean;
+    /** Disables the user interaction. */
+    disabled?: boolean;
+    /** Fired when the tab asks to be closed, either from its close button or the `Delete` key. */
+    onClose?: (event: Event, value: string) => void;
+} & HTMLAttributes<HTMLDivElement>;

package/dist/components/tab-view/types.js

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

package/dist/components/top-nav/docs/llms.md

@@ -0,0 +1,176 @@
+# TopNav
+
+TopNav gives a single selection from a row of items, with a bar that marks the selected one. Each item carries a short label and often an icon.
+
+The bar belongs to the strip rather than to any one item: when the selection moves it travels to the item that took it, staying on screen the whole way instead of disappearing from one and reappearing under the next.
+
+The strip owns the selection and nothing else. What an item opens is rendered by you, wherever it belongs on the page, so an item can open a panel underneath it, swap a region somewhere else, or drive a route.
+
+To create a top nav, you will need to use the following components:
+
+- `TopNav`: The root component that creates the context every item reads: which item is selected, the appearance, the size and the axis. It renders the `tablist` and the bar that travels across it.
+- `TopNavItem`: A single item of the strip. It reports its own selection and can carry an icon.
+
+## Usage
+
+A top nav expects a `value` on every item and a `selectedValue` to match it against. Bind `selectedValue` to follow the selection, and render whatever the selected item opens yourself.
+
+```svelte
+<script>
+	import { TopNav, TopNavItem } from 'fluentui-svelte';
+
+	let selectedValue = $state('arrivals');
+</script>
+
+<TopNav bind:selectedValue aria-label="Flights">
+	<TopNavItem id="tab-arrivals" value="arrivals">Arrivals</TopNavItem>
+	<TopNavItem id="tab-departures" value="departures">Departures</TopNavItem>
+</TopNav>
+
+{#if selectedValue === 'arrivals'}
+	<div role="tabpanel" aria-labelledby="tab-arrivals">Everything landing in the next hour.</div>
+{:else}
+	<div role="tabpanel" aria-labelledby="tab-departures">Everything leaving in the next hour.</div>
+{/if}
+```
+
+## Examples
+
+### Appearance
+
+`appearance` decides how the strip is painted. `transparent` has no background of its own and `subtle` fills an item while it is engaged; both mark the selection with the travelling bar. The two circular appearances trade that bar for a pill: `subtle-circular` outlines the selected item and `filled-circular` fills it.
+
+```svelte
+<TopNav appearance="transparent">...</TopNav>
+<TopNav appearance="subtle">...</TopNav>
+<TopNav appearance="subtle-circular">...</TopNav>
+<TopNav appearance="filled-circular">...</TopNav>
+```
+
+### Size
+
+`size` sets the padding, the type and the thickness of the bar for every item at once.
+
+```svelte
+<TopNav size="small">...</TopNav>
+<TopNav size="medium">...</TopNav>
+<TopNav size="large">...</TopNav>
+```
+
+### Vertical
+
+`vertical` stacks the items in a column and moves the bar to their leading edge, where it travels up and down instead of across. The arrow keys follow the same turn.
+
+```svelte
+<TopNav bind:selectedValue vertical>
+	<TopNavItem value="tab1">First Tab</TopNavItem>
+	<TopNavItem value="tab2">Second Tab</TopNavItem>
+</TopNav>
+```
+
+### Icon
+
+`icon` takes a snippet or a component and renders it before the label.
+
+```svelte
+<script>
+	import { TopNav, TopNavItem } from 'fluentui-svelte';
+	import { AirplaneRegular, AirplaneTakeOffRegular } from 'fluentui-icons-svelte';
+</script>
+
+<TopNav bind:selectedValue>
+	<TopNavItem value="arrivals" icon={AirplaneRegular}>Arrivals</TopNavItem>
+	<TopNavItem value="departures" icon={AirplaneTakeOffRegular}>Departures</TopNavItem>
+</TopNav>
+```
+
+### As an Anchor
+
+`as="a"` renders the item as an anchor and takes the attributes of one, `href` among them, so the item has a real URL to open in a new tab or copy. It still reports as a `tab`, which is what a strip of tabs over one page should be; if the items are navigation between pages rather than tabs, a `nav` of plain links is the better shape.
+
+```svelte
+<TopNav bind:selectedValue>
+	<TopNavItem as="a" href="#arrivals" value="arrivals">Arrivals</TopNavItem>
+	<TopNavItem as="a" href="#departures" value="departures">Departures</TopNavItem>
+</TopNav>
+```
+
+### Disabled
+
+`disabled` on the strip disables every item at once, and a single item can be disabled on its own. The arrow keys pass over a disabled item rather than landing on it.
+
+```svelte
+<TopNav disabled>...</TopNav>
+
+<TopNav>
+	<TopNavItem value="tab1">First Tab</TopNavItem>
+	<TopNavItem value="tab2" disabled>Second Tab</TopNavItem>
+</TopNav>
+```
+
+### Select on Focus
+
+`selectTabOnFocus` selects an item as soon as the focus reaches it, so the arrow keys move the selection rather than only the focus. Use it when what an item opens is already on the page; leave it off when opening one costs a request.
+
+```svelte
+<TopNav bind:selectedValue selectTabOnFocus>
+	<TopNavItem value="tab1">First Tab</TopNavItem>
+	<TopNavItem value="tab2">Second Tab</TopNavItem>
+</TopNav>
+```
+
+### Reserved Space
+
+A selected item sets its label in semibold, which is wider than the same label at rest. `reserveSelectedTabSpace` is on by default and holds that width from the start, so selecting an item never shoves the ones beside it along. Turning it off lets the items size to what they are showing, and the row shifts as the selection moves.
+
+```svelte
+<TopNav bind:selectedValue reserveSelectedTabSpace={false}>
+	<TopNavItem value="tab1">First Tab</TopNavItem>
+	<TopNavItem value="tab2">Second Tab</TopNavItem>
+</TopNav>
+```
+
+## Component Props (TopNav)
+
+<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
+<!-- props:TopNavProps -->
+
+| Name                       | Type                                                                           | Default         | Description                                                                                                                                                                         |
+| -------------------------- | ------------------------------------------------------------------------------ | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ref` _bindable_           | `HTMLDivElement`                                                               |                 | The DOM reference of the strip.                                                                                                                                                     |
+| `selectedValue` _bindable_ | `string`                                                                       |                 | The value of the selected item.                                                                                                                                                     |
+| `onTabSelect`              | `(event: Event, value: string) => void`                                        |                 | Fired when an item is selected.                                                                                                                                                     |
+| `appearance`               | [`TopNavAppearance`](https://fluentui-svelte.dev/docs/types/#topnavappearance) | `'transparent'` | How the strip is painted: `transparent` has no background of its own, `subtle` fills an item while it is engaged, and the two circular appearances trade the moving bar for a pill. |
+| `size`                     | `'small'` &#124; `'medium'` &#124; `'large'`                                   | `'medium'`      | The size of every item of the strip.                                                                                                                                                |
+| `vertical`                 | `boolean`                                                                      | `false`         | Arranges the items in a column, with the bar down their leading edge.                                                                                                               |
+| `disabled`                 | `boolean`                                                                      | `false`         | Disables the user interaction on every item.                                                                                                                                        |
+| `selectTabOnFocus`         | `boolean`                                                                      | `false`         | Selects an item as soon as the focus reaches it, rather than waiting to be asked.                                                                                                   |
+| `reserveSelectedTabSpace`  | `boolean`                                                                      | `true`          | A selected item sets its label in semibold, which is wider than the same label at rest. This holds that width from the start, so selecting an item never shifts the ones beside it. |
+| `disableTabspot`           | `boolean`                                                                      | `false`         | Opts the strip out of the tabspot focus management, to wire your own.                                                                                                               |
+| Element Attributes (`div`) |                                                                                |                 |                                                                                                                                                                                     |
+
+<!-- /props:TopNavProps -->
+
+## Component Props (TopNavItem)
+
+<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
+<!-- props:TopNavItemProps -->
+
+| Name             | Type                          | Default    | Description                                                                                                                        |
+| ---------------- | ----------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `ref` _bindable_ | `TopNavItemElementDOMType[T]` |            | The DOM reference of the item.                                                                                                     |
+| `as`             | `'button'` &#124; `'a'`       | `'button'` | The DOM element to render. An anchor takes the attributes of one, `href` among them, and is what an item that navigates should be. |
+| `value`          | `string`                      |            | The value that identifies the item. Defaults to a generated id.                                                                    |
+| `icon`           | `Snippet` &#124; `Component`  |            | The icon to display before the label.                                                                                              |
+| `disabled`       | `boolean`                     |            | Disables the user interaction.                                                                                                     |
+| HTML Attributes  |                               |            |                                                                                                                                    |
+
+<!-- /props:TopNavItemProps -->
+
+## Keyboard Navigation
+
+The strip is a single tab stop. The arrows walk the items along the axis they are laid out on, `Home` and `End` jump to the ends, and `Enter` and `Space` select the focused item — or `selectTabOnFocus` selects it on arrival. `disableTabspot` hands the focus management back to you.
+
+## Accessibility
+
+The strip renders a `tablist` and every item a `tab`, so give it a name through `aria-label`. Since you render what an item opens, give that element a `tabpanel` role and point its `aria-labelledby` at the `id` of its item. An item with an icon and no label needs an `aria-label` of its own.

package/dist/components/top-nav/top-nav-item.svelte

@@ -0,0 +1,234 @@
+<script lang="ts" generics="T extends TopNavItemGenerics = 'button'">
+	import { invokeHandlers, RenderSoC } from '../../internal/index.js';
+	import { COMPONENT_NAME, requireTopNavContext } from './top-nav.svelte.js';
+	import type { TopNavItemElementDOMType, TopNavItemGenerics, TopNavItemProps } from './types.js';
+
+	const ID = $props.id();
+
+	let {
+		as = 'button' as T,
+		ref = $bindable(),
+		value = `${COMPONENT_NAME}-${ID}`,
+		icon,
+		disabled,
+		onclick,
+		onfocus,
+		class: classes,
+		children,
+		...attributes
+	}: TopNavItemProps<T> = $props();
+
+	const context = requireTopNavContext();
+
+	const selected = $derived(context.state.selectedValue === value);
+
+	/** The item can be disabled on its own, and the strip can disable every one of them at once. */
+	const _disabled = $derived(disabled || context.config.disabled);
+
+	/**
+	 * The tag the invariant rules over. The markup renders it through here, so it is checked during
+	 * SSR and on every prop update rather than only once on mount.
+	 */
+	const _as = $derived.by(() => {
+		if (as !== 'button' && as !== 'a') throw new Error(`Invalid tag: ${as}. Must be one of button, a`);
+		return as;
+	});
+</script>
+
+<!--
+	@component
+	A single item of a `TopNav`. It reports its own selection and can carry an icon.
+
+	- Usage:
+	```tsx
+	<script>
+		import { TopNav, TopNavItem } from 'fluentui-svelte';
+		import { AirplaneRegular } from 'fluentui-icons-svelte';
+	</script>
+
+	<TopNav selectedValue="arrivals" aria-label="Flights">
+		<TopNavItem value="arrivals" icon={AirplaneRegular}>Arrivals</TopNavItem>
+		<TopNavItem as="a" href="/departures" value="departures">Departures</TopNavItem>
+	</TopNav>
+	```
+-->
+<svelte:element
+	this={_as}
+	bind:this={ref as TopNavItemElementDOMType[T]}
+	type={_as === 'button' ? 'button' : undefined}
+	role="tab"
+	data-value={value}
+	aria-selected={selected}
+	disabled={_as === 'button' ? _disabled : undefined}
+	aria-disabled={_as === 'a' && _disabled ? true : undefined}
+	class={[
+		'fs-top-nav-item',
+		context.config.appearance,
+		{ selected, vertical: context.config.vertical, disabled: _disabled },
+		classes
+	]}
+	onclick={(e: MouseEvent) => invokeHandlers(e, _disabled, [() => context.methods.selectTab(e, value), onclick])}
+	onfocus={(e: FocusEvent) =>
+		invokeHandlers(e, _disabled, [
+			() => context.config.selectTabOnFocus && context.methods.selectTab(e, value),
+			onfocus
+		])}
+	{...attributes}
+>
+	{#if icon}
+		<span class="fs-top-nav-item-icon">
+			<RenderSoC SoC={icon} />
+		</span>
+	{/if}
+	<span class="fs-top-nav-item-content">
+		{@render children?.()}
+		{#if context.config.reserveSelectedTabSpace}
+			<!--
+				The label again, in the weight it takes once selected, laid out but never shown. The item
+				is then already as wide as its widest state, so selecting it cannot shove its neighbours
+				along. It is held out of the accessibility tree, where it would read as a second label.
+			-->
+			<span class="fs-top-nav-item-reserve" aria-hidden="true">{@render children?.()}</span>
+		{/if}
+	</span>
+</svelte:element>
+
+<style>
+	.fs-top-nav-item {
+		position: relative;
+		display: flex;
+		flex: 0 0 auto;
+		align-items: center;
+		justify-content: center;
+		gap: var(--fs-top-nav-item-gap, 0.5rem);
+		padding: var(--fs-top-nav-item-padding-block, 0.375rem) var(--fs-top-nav-item-padding-inline, 0.375rem);
+		border: none;
+		border-radius: var(--fs-control-border-radius);
+		background: transparent;
+		color: var(--fs-text-secondary);
+		font-family: inherit;
+		font-size: var(--fs-top-nav-item-font-size, var(--fs-body2-font-size));
+		line-height: var(--fs-top-nav-item-line-height, var(--fs-body2-line-height));
+		white-space: nowrap;
+		/* An anchor arrives underlined and in the colour of a link; an item is neither. */
+		text-decoration: none;
+		cursor: pointer;
+		user-select: none;
+		outline: none;
+		transition:
+			color var(--fs-fast-duration) var(--fs-point-to-point),
+			background var(--fs-fast-duration) var(--fs-point-to-point);
+		&:hover {
+			color: var(--fs-text-primary);
+		}
+		&:active {
+			color: var(--fs-text-secondary);
+		}
+		&:focus-visible {
+			outline: 0.125rem var(--fs-focus-stroke-outer) solid;
+			outline-offset: 0.125rem;
+		}
+		&.selected {
+			color: var(--fs-text-primary);
+			font-weight: 600;
+		}
+		/* An anchor has no `:disabled` of its own, so the class is what both tags answer to. */
+		&.disabled {
+			color: var(--fs-text-disabled);
+			cursor: not-allowed;
+		}
+		/*
+		 * The line an item shows under itself while the pointer is on it. It is the item's own, not
+		 * the bar of the strip: the bar belongs to whatever is selected and never leaves it.
+		 */
+		&::after {
+			content: '';
+			position: absolute;
+			left: var(--fs-top-nav-item-padding-inline, 0.375rem);
+			right: var(--fs-top-nav-item-padding-inline, 0.375rem);
+			bottom: 0;
+			height: var(--fs-top-nav-bar-thickness, 0.1875rem);
+			border-radius: var(--fs-top-nav-bar-thickness, 0.1875rem);
+			background: var(--fs-control-strong-stroke-disabled);
+			opacity: 0;
+			transition: opacity var(--fs-fast-duration) var(--fs-point-to-point);
+			pointer-events: none;
+		}
+		&:hover:not(.selected):not(.disabled)::after {
+			opacity: 1;
+		}
+		&.vertical::after {
+			left: auto;
+			right: auto;
+			inset-inline-start: 0;
+			top: var(--fs-top-nav-item-padding-block, 0.375rem);
+			bottom: var(--fs-top-nav-item-padding-block, 0.375rem);
+			width: var(--fs-top-nav-bar-thickness, 0.1875rem);
+			height: auto;
+		}
+		&.subtle {
+			&:hover:not(.disabled) {
+				background: var(--fs-subtle-fill-secondary);
+			}
+			&:active:not(.disabled) {
+				background: var(--fs-subtle-fill-tertiary);
+			}
+		}
+		/* A pill takes the place of the bar, so the hover line steps aside for it. */
+		&.subtle-circular,
+		&.filled-circular {
+			border-radius: 999rem;
+			&::after {
+				content: none;
+			}
+			&:hover:not(.disabled) {
+				background: var(--fs-subtle-fill-secondary);
+			}
+			&:active:not(.disabled) {
+				background: var(--fs-subtle-fill-tertiary);
+			}
+		}
+		&.filled-circular {
+			background: var(--fs-subtle-fill-secondary);
+		}
+		&.subtle-circular.selected {
+			background: var(--fs-system-attention-bg);
+			box-shadow: inset 0 0 0 1px color-mix(in srgb, var(--fs-system-attention-text), transparent 50%);
+			color: var(--fs-system-attention-text);
+		}
+		&.filled-circular.selected {
+			background: var(--fs-accent-fill-default);
+			color: var(--fs-text-on-accent-primary);
+			&:hover:not(.disabled) {
+				background: var(--fs-accent-fill-secondary);
+			}
+			&:active:not(.disabled) {
+				background: var(--fs-accent-fill-tertiary);
+			}
+			&.disabled {
+				background: var(--fs-accent-fill-disabled);
+				color: var(--fs-text-on-accent-disabled);
+			}
+		}
+		& .fs-top-nav-item-icon {
+			display: flex;
+			flex: 0 0 auto;
+			align-items: center;
+			justify-content: center;
+			& :global(svg) {
+				width: var(--fs-top-nav-item-icon-size, 1.25rem);
+				height: var(--fs-top-nav-item-icon-size, 1.25rem);
+			}
+		}
+		& .fs-top-nav-item-content {
+			display: block;
+		}
+		& .fs-top-nav-item-reserve {
+			display: block;
+			height: 0;
+			overflow: hidden;
+			visibility: hidden;
+			font-weight: 600;
+		}
+	}
+</style>

package/dist/components/top-nav/top-nav-item.svelte.d.ts

@@ -0,0 +1,41 @@
+import type { TopNavItemGenerics, TopNavItemProps } from './types.ts';
+declare function $$render<T extends TopNavItemGenerics = 'button'>(): {
+    props: TopNavItemProps<T>;
+    exports: {};
+    bindings: "ref";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<T extends TopNavItemGenerics = 'button'> {
+    props(): ReturnType<typeof $$render<T>>['props'];
+    events(): ReturnType<typeof $$render<T>>['events'];
+    slots(): ReturnType<typeof $$render<T>>['slots'];
+    bindings(): "ref";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <T extends TopNavItemGenerics = 'button'>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<T>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<T>['props']>, ReturnType<__sveltets_Render<T>['events']>, ReturnType<__sveltets_Render<T>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<T>['bindings']>;
+    } & ReturnType<__sveltets_Render<T>['exports']>;
+    <T extends TopNavItemGenerics = 'button'>(internal: unknown, props: ReturnType<__sveltets_Render<T>['props']> & {}): ReturnType<__sveltets_Render<T>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
+}
+/**
+ * A single item of a `TopNav`. It reports its own selection and can carry an icon.
+ *
+ * - Usage:
+ * ```tsx
+ * <script>
+ * 	import { TopNav, TopNavItem } from 'fluentui-svelte';
+ * 	import { AirplaneRegular } from 'fluentui-icons-svelte';
+ * </script>
+ *
+ * <TopNav selectedValue="arrivals" aria-label="Flights">
+ * 	<TopNavItem value="arrivals" icon={AirplaneRegular}>Arrivals</TopNavItem>
+ * 	<TopNavItem as="a" href="/departures" value="departures">Departures</TopNavItem>
+ * </TopNav>
+ * ```
+ */
+declare const TopNavItem: $$IsomorphicComponent;
+type TopNavItem<T extends TopNavItemGenerics = 'button'> = InstanceType<typeof TopNavItem<T>>;
+export default TopNavItem;