fluentui-svelte 0.6.0 → 0.7.0

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

@@ -0,0 +1,110 @@
+# SideNav
+
+App navigation built on ListView. SideNavItem renders an anchor by default. Use `as="button"` for actions, or `as="li"` / `as="div"` for content with multiple controls. The navigation owns no router: set href and active from your app's current route.
+
+## Usage
+
+```svelte
+<script>
+	import { AppWindow, AppSurface, SideNav, SideNavItem } from 'fluentui-svelte';
+	import { HomeRegular, FolderRegular, SettingsRegular } from 'fluentui-icons-svelte';
+</script>
+
+<AppWindow width={480} height={240}>
+	<SideNav header="Workspace">
+		<SideNavItem href="#home" label="Home" icon={HomeRegular} active />
+		<SideNavItem href="#documents" label="Documents" icon={FolderRegular} />
+		<SideNavItem href="#settings" label="Settings" icon={SettingsRegular} />
+	</SideNav>
+	<AppSurface style="padding: 1rem">Page content</AppSurface>
+</AppWindow>
+```
+
+SideNav also works on its own, in any container with a height. Use `bind:collapsed` to control it, `SideNavBranch` to nest items and the `footer` snippet to pin items to the bottom.
+
+## Modes and accessibility
+
+Docked navigation occupies layout space and collapses to an icon rail. Labels remain available to assistive technology. Items without icons show their initial in the rail. Opening a branch from the rail expands the navigation first.
+
+With `floating`, SideNav overlays AppWindow's body below its optional TitleBar. Closed floating navigation shows only the hamburger; opening it does not move page content. It is non-modal and does not trap focus. Escape, an outside pointer press, moving focus outside, and activating a SideNavItem close it. Set `closeOnSelect={false}` to keep it open after activation. A standalone floating SideNav needs a positioned parent.
+
+Inside an AppWindow whose TitleBar has a global navigation button (`TitleBarLeftControls globalNav`), that button expands and collapses the SideNav, follows its state in `aria-expanded`, and SideNav hides its own hamburger. Set `showToggle` to `true` to keep both, or to `false` to hide the hamburger and control it yourself (`getAppWindowContext().state.sideNav.setCollapsed`). While a floating navigation is open, the global button is not an outside press.
+
+The Button toggle exposes aria-expanded and aria-controls. SideNav is a named navigation landmark with native lists and links. The underlying ListView supplies arrow navigation, disabled-item handling and selection. Avoid menu/listbox roles for ordinary route navigation. There is no back button.
+
+## Custom content and footer
+
+Only two regions accept text, snippets or components: `topContent`, between the hamburger section and the list, and `footerContent`, after the list and before the pinned navigation footer. Strings render as text and are hidden in the compact rail. Snippets receive `{ collapsed, floating }`; components receive these as props, so they can render compact controls or hide their content. Use a snippet to supply other required component props.
+
+The header is plain text. SideNavItem uses its label or ordinary ListViewItem children markup. The `footer` snippet contains navigation entries and remains pinned while the main list scrolls. Compose real Menu, TextBox, Avatar and Button components in the two custom regions.
+
+## ListView customization
+
+`listViewProps` customizes every list of the navigation: the main one, the footer and the ones inside a SideNavBranch. Defaults are role="list", selectionMode="none" and navigationMode="items". Keep native list semantics when using branches. Selection can be enabled and bound through `selectedItems`, shared across all of them. Set each item's value when using selection.
+
+## Component Props (SideNav)
+
+<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
+<!-- props:SideNavProps -->
+
+| Name                                             | Type                                         | Default                 | Description                                                                                                                                                                                                                                                     |
+| ------------------------------------------------ | -------------------------------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ref` _bindable_                                 | `HTMLElement` &#124; `null`                  |                         | The DOM reference of the navigation landmark.                                                                                                                                                                                                                   |
+| `label`                                          | `string`                                     | `'Main navigation'`     | The accessible name of the navigation landmark.                                                                                                                                                                                                                 |
+| `collapsed` _bindable_                           | `boolean`                                    | `false`                 | Shows an icon rail when docked, or only the toggle when floating.                                                                                                                                                                                               |
+| `position`                                       | `'left'` &#124; `'right'`                    | `'left'`                | The side of the window the navigation is on. It mirrors in right-to-left layouts, and AppSurface rounds the corners that face it.                                                                                                                               |
+| `showToggle`                                     | `boolean`                                    | `Automatic`             | Whether the navigation shows its own hamburger toggle. By default it hides it when the title bar of its window has a global navigation button, which then controls the navigation. Set it to true to keep both, or to false to control the navigation yourself. |
+| `floating`                                       | `boolean`                                    | `false`                 | Overlays the content of a positioned parent instead of taking layout space. The overlay is non-modal.                                                                                                                                                           |
+| `width`                                          | `number` &#124; `string`                     | `200`                   | The expanded width. Numbers are pixels converted to rem; strings are CSS lengths.                                                                                                                                                                               |
+| `expandLabel`                                    | `string`                                     | `'Expand navigation'`   | The accessible label of the toggle while collapsed.                                                                                                                                                                                                             |
+| `collapseLabel`                                  | `string`                                     | `'Collapse navigation'` | The accessible label of the toggle while expanded.                                                                                                                                                                                                              |
+| `closeOnSelect`                                  | `boolean`                                    | `true`                  | Closes a floating panel after activating a SideNavItem.                                                                                                                                                                                                         |
+| `onCollapsedChange`                              | `(event: Event, collapsed: boolean) => void` |                         | Called when the user expands or collapses the navigation.                                                                                                                                                                                                       |
+| `selectedItems` _bindable_                       | `string[]`                                   |                         | The selection shared by every list in the navigation. Selection is off by default.                                                                                                                                                                              |
+| `listViewProps`                                  | `SideNavListViewProps`                       |                         | Overrides the defaults of every list in the navigation, the main one, the footer and the ones inside a SideNavBranch: native list semantics, no selection and one tab stop per item.                                                                            |
+| `header`                                         | `string`                                     |                         | The text heading beside the hamburger button. Hidden in the compact rail.                                                                                                                                                                                       |
+| `topContent`                                     | `string` &#124; `Snippet` &#124; `Component` |                         | Custom content between the hamburger section and the list. Text, snippets and components are supported. Renderers receive collapsed and floating; strings are hidden in the compact rail.                                                                       |
+| `footerContent`                                  | `string` &#124; `Snippet` &#124; `Component` |                         | Custom content after the scrolling list and before the pinned footer. Text, snippets and components are supported. Renderers receive collapsed and floating; strings are hidden in the compact rail.                                                            |
+| `footer`                                         | `Snippet`                                    |                         | Footer list items pinned to the bottom, outside the main list's scroll area.                                                                                                                                                                                    |
+| `children`                                       | `Snippet`                                    |                         | Main navigation items. Use SideNavItem and SideNavBranch.                                                                                                                                                                                                       |
+| `HTMLAttributes<HTMLElement>` without `children` |                                              |                         |                                                                                                                                                                                                                                                                 |
+
+<!-- /props:SideNavProps -->
+
+## Component Props (SideNavItem)
+
+<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
+<!-- props:SideNavItemProps -->
+
+| Name                                                                                                        | Type                                                                                          | Default | Description                                                                                    |
+| ----------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | ------- | ---------------------------------------------------------------------------------------------- |
+| `as`                                                                                                        | `'li'` &#124; `'a'` &#124; `'button'` &#124; `'div'`                                          | `'a'`   | The HTML tag. Links are the default; use button for actions and li or div for custom controls. |
+| `ref` _bindable_                                                                                            | `HTMLLIElement` &#124; `HTMLAnchorElement` &#124; `HTMLButtonElement` &#124; `HTMLDivElement` |         | The DOM reference of the item.                                                                 |
+| `label`                                                                                                     | `string`                                                                                      |         | The accessible label, also used as visible content when children are absent.                   |
+| `icon`                                                                                                      | `Snippet` &#124; `Component`                                                                  |         | The decorative icon shown in both expanded and collapsed modes.                                |
+| `children`                                                                                                  | `Snippet`                                                                                     |         | Optional item markup, following ListViewItem. The label is rendered when children are absent.  |
+| `shape`, `value`, `active`, `role`, `disabled`, `checkmark`, `onAction`, `onfocus` from `ListViewItemProps` |                                                                                               |         |                                                                                                |
+| HTML Attributes                                                                                             |                                                                                               |         |                                                                                                |
+
+<!-- /props:SideNavItemProps -->
+
+## Component Props (SideNavBranch)
+
+<!-- DO NOT EDIT THIS SECTION (propsmith generated) -->
+<!-- props:SideNavBranchProps -->
+
+| Name                                                                                                 | Type                                    | Default | Description                                                                                                                                                                                    |
+| ---------------------------------------------------------------------------------------------------- | --------------------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `label`                                                                                              | `string`                                |         | The accessible label of the disclosure button. In the compact rail, its initial stands in when there is no icon.                                                                               |
+| `icon`                                                                                               | `Snippet` &#124; `Component`            |         | The decorative icon before the label.                                                                                                                                                          |
+| `expanded` _bindable_                                                                                | `boolean`                               | `false` | Whether the nested items are visible. Branches only expand or collapse and are never selectable. The compact rail reports a branch as collapsed, and opens the navigation when one is pressed. |
+| `onExpandedChange`                                                                                   | `(e: Event, expanded: boolean) => void` |         | Called when a user expands or collapses the branch.                                                                                                                                            |
+| `disabled`                                                                                           | `boolean`                               | `false` | Disables the disclosure button.                                                                                                                                                                |
+| `ref` _bindable_                                                                                     | `HTMLButtonElement`                     |         | The DOM reference of the native disclosure button. Additional HTML attributes, including class and id, also target this button.                                                                |
+| `wrapperRef` _bindable_                                                                              | `HTMLLIElement` &#124; `HTMLDivElement` |         | The DOM reference of the wrapper element, the list item that holds the button and the nested list.                                                                                             |
+| `wrapperAttributes`                                                                                  | `HTMLAttributes`                        |         | The attributes to spread on the wrapper element.                                                                                                                                               |
+| `shape`                                                                                              | `ListViewItemBranchProps['shape']`      |         | The disclosure button shape. Inherited from the list by default.                                                                                                                               |
+| `children`                                                                                           | `Snippet`                               |         | The nested SideNavItem and SideNavBranch content.                                                                                                                                              |
+| `HTMLButtonAttributes` without `children`, `role`, `type`, `value`, `aria-expanded`, `aria-controls` |                                         |         |                                                                                                                                                                                                |
+
+<!-- /props:SideNavBranchProps -->

package/dist/components/side-nav/side-nav-branch.svelte

@@ -0,0 +1,43 @@
+<script lang="ts">
+	import ListViewItemBranch from '../list-view/list-view-item-branch.svelte';
+	import SideNavList from './side-nav-list.svelte';
+	import { getSideNavContext } from './side-nav.js';
+	import type { SideNavBranchProps } from './types.js';
+
+	let {
+		ref = $bindable(null),
+		wrapperRef = $bindable(null),
+		expanded = $bindable(false),
+		label,
+		wrapperAttributes,
+		icon,
+		onclick,
+		children,
+		...attributes
+	}: SideNavBranchProps = $props();
+
+	const context = getSideNavContext();
+	// The rail hides the branch, so the branch reports collapsed there without losing its own state.
+	const visiblyExpanded = () => expanded && !context?.state.compact;
+</script>
+
+{#snippet initial()}<span>{label.slice(0, 1)}</span>{/snippet}
+
+<ListViewItemBranch
+	{...attributes}
+	{label}
+	wrapperAttributes={{ class: `fs-side-nav-branch ${wrapperAttributes?.class ?? ''}`, ...wrapperAttributes }}
+	icon={icon ?? (context?.state.compact ? initial : undefined)}
+	bind:ref
+	bind:wrapperRef
+	bind:expanded={visiblyExpanded, (value) => (expanded = value)}
+	onclick={(event) => {
+		onclick?.(event);
+		// A branch cannot open inside the rail, so the rail opens first.
+		if (!event.defaultPrevented) context?.methods.setCollapsed(event, false);
+	}}
+>
+	<SideNavList>
+		{@render children?.()}
+	</SideNavList>
+</ListViewItemBranch>

package/dist/components/side-nav/side-nav-branch.svelte.d.ts

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

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

@@ -0,0 +1,75 @@
+<script lang="ts" generics="T extends 'li' | 'a' | 'button' | 'div' = 'a'">
+	import ListViewItem from '../list-view/list-view-item.svelte';
+	import { RenderSoC } from '../../internal/index.js';
+	import { getSideNavContext } from './side-nav.js';
+	import type { SideNavItemProps } from './types.js';
+	import type { ListViewItemProps } from '../list-view/types.js';
+
+	let {
+		as = 'a' as T,
+		ref = $bindable(null),
+		label,
+		icon,
+		children,
+		onAction,
+		...attributes
+	}: SideNavItemProps<T> = $props();
+
+	// Outside a SideNav the item is a plain, expanded one: it has no rail to fit and no panel to close.
+	const context = getSideNavContext();
+	const Item = ListViewItem<T>;
+	const compact = $derived(context?.state.compact ?? false);
+
+	function handleAction(event: MouseEvent, value: string) {
+		onAction?.(event, value);
+		context?.methods.activate(event);
+	}
+</script>
+
+<Item
+	{as}
+	bind:ref
+	aria-label={label}
+	title={compact ? label : undefined}
+	{...attributes as unknown as ListViewItemProps<T>}
+	onAction={as === 'a' || as === 'button' || onAction ? handleAction : undefined}
+>
+	{#if icon}
+		<span class="fs-side-nav-item-icon" aria-hidden="true">
+			<RenderSoC SoC={icon} />
+		</span>
+	{:else if compact}
+		<span class="fs-side-nav-item-icon" aria-hidden="true">
+			{label.slice(0, 1)}
+		</span>
+	{/if}
+	<span class="fs-side-nav-item-label" hidden={compact}>
+		{#if children}
+			{@render children()}
+		{:else}
+			{label}
+		{/if}
+	</span>
+</Item>
+
+<style>
+	.fs-side-nav-item-icon {
+		display: inline-flex;
+		align-items: center;
+		justify-content: center;
+		flex: none;
+		inline-size: 1rem;
+		/* As tall as a line of text, so an item is as tall with its label as without it. */
+		block-size: 1lh;
+		& :global(svg) {
+			inline-size: 1rem;
+			block-size: 1rem;
+		}
+	}
+	.fs-side-nav-item-label {
+		min-inline-size: 0;
+		overflow: hidden;
+		text-overflow: ellipsis;
+		white-space: nowrap;
+	}
+</style>

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

@@ -0,0 +1,25 @@
+import type { SideNavItemProps } from './types.ts';
+declare function $$render<T extends 'li' | 'a' | 'button' | 'div' = 'a'>(): {
+    props: SideNavItemProps<T>;
+    exports: {};
+    bindings: "ref";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<T extends 'li' | 'a' | 'button' | 'div' = 'a'> {
+    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 'li' | 'a' | 'button' | 'div' = 'a'>(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 'li' | 'a' | 'button' | 'div' = 'a'>(internal: unknown, props: ReturnType<__sveltets_Render<T>['props']> & {}): ReturnType<__sveltets_Render<T>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
+}
+declare const SideNavItem: $$IsomorphicComponent;
+type SideNavItem<T extends 'li' | 'a' | 'button' | 'div' = 'a'> = InstanceType<typeof SideNavItem<T>>;
+export default SideNavItem;

package/dist/components/side-nav/side-nav-list.svelte

@@ -0,0 +1,32 @@
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+	import ListView from '../list-view/list-view.svelte';
+	import { getSideNavContext } from './side-nav.js';
+
+	let { children }: { children?: Snippet } = $props();
+
+	const context = getSideNavContext();
+
+	// Escape belongs to the enclosing panel: ListView keeps its other navigation keys.
+	const MANAGED_KEYS = { Home: true, End: true, PageUp: true, PageDown: true };
+
+	// Outside a SideNav, a branch keeps the selection of its own list.
+	let ownSelectedItems = $state<string[]>([]);
+</script>
+
+<ListView
+	role="list"
+	selectionMode="none"
+	navigationMode="items"
+	manageSpecialKeys={MANAGED_KEYS}
+	{...context?.config.listViewProps}
+	bind:selectedItems={
+		() => context?.state.selectedItems ?? ownSelectedItems,
+		(value) => {
+			if (context) context.state.selectedItems = value;
+			else ownSelectedItems = value;
+		}
+	}
+>
+	{@render children?.()}
+</ListView>

package/dist/components/side-nav/side-nav-list.svelte.d.ts

@@ -0,0 +1,7 @@
+import type { Snippet } from 'svelte';
+type $$ComponentProps = {
+    children?: Snippet;
+};
+declare const SideNavList: import("svelte").Component<$$ComponentProps, {}, "">;
+type SideNavList = ReturnType<typeof SideNavList>;
+export default SideNavList;

package/dist/components/side-nav/side-nav.d.ts

@@ -0,0 +1,2 @@
+import type { SideNavContext } from './types.ts';
+export declare const getSideNavContext: () => SideNavContext | null, setSideNavContext: (context: SideNavContext) => void;

package/dist/components/side-nav/side-nav.js

@@ -0,0 +1,2 @@
+import { createFSContext } from '../../internal/index.js';
+export const [getSideNavContext, setSideNavContext] = createFSContext();