fluentui-svelte 0.2.1 → 0.4.0

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

@@ -0,0 +1,287 @@
+import type { FSContext } from '../../internal/index.js';
+import type { PolymorphicProps } from '../../types/index.js';
+import type { Component, Snippet } from 'svelte';
+import type { CheckboxProps } from '../checkbox/types.ts';
+import type { RadioButtonProps } from '../radio-button/types.ts';
+export type TableSize = 'extra-small' | 'small' | 'medium';
+export type CellFocusMode = 'cell' | 'group' | 'none';
+export type TableRowAppearance = 'none' | 'brand' | 'neutral';
+export type SortDirection = 'ascending' | 'descending';
+export type SelectionType = 'checkbox' | 'radio';
+export type TableDOM = {
+    table: HTMLTableElement;
+    thead: HTMLTableSectionElement;
+    tbody: HTMLTableSectionElement;
+    tr: HTMLTableRowElement;
+    th: HTMLTableCellElement;
+    td: HTMLTableCellElement;
+    div: HTMLDivElement;
+};
+/** @propsmith TableProps */
+export type TableProps<Tag extends 'table' | 'div' = 'table'> = {
+    /** The HTML element to render the table as. Defaults to a `div` when `noNativeElements` is set.
+     * @type 'table' | 'div'
+     * @default 'table'
+     */
+    as?: Tag;
+    /** The DOM reference of the table element.
+     * @type HTMLTableElement | HTMLDivElement
+     * @bindable
+     */
+    ref?: TableDOM[Tag] | HTMLDivElement;
+    /** Affects the sizes of all table subcomponents.
+     * @default 'medium'
+     */
+    size?: TableSize;
+    /** Renders every table part as a `div` instead of a semantic table element. The layout switches
+     * from `display: table` to `display: flex`, which virtualization and sticky headers need.
+     * @default false
+     */
+    noNativeElements?: boolean;
+    /** Turns every header cell into a sort button. Individual cells can still opt in on their own.
+     * @default false
+     */
+    sortable?: boolean;
+    /** Drops the line that separates one row from the next.
+     * @default false
+     */
+    noRowBorders?: boolean;
+    /** Moves the focus between cells with the arrow keys, through a single tab stop. It also
+     * switches the table over to the `role="grid"` pattern, which that navigation requires.
+     * @default false
+     */
+    enableTabspot?: boolean;
+    /** Lets the arrow keys reach rows a windowed list has not rendered. Only read when
+     * `enableTabspot` is set, and the rows need an `aria-rowindex` for it to find them again.
+     * @type TableVirtualizer
+     */
+    virtualizer?: TableVirtualizer;
+    /** Gives every header cell a handle that drags its column wider or narrower. It also pins the
+     * table to a fixed layout, so a column keeps the width it was given.
+     * @default false
+     */
+    resizableColumns?: boolean;
+    /** The width of each column in pixels, by column position. Columns left out keep their own size.
+     * @bindable
+     */
+    columnWidths?: number[];
+    /** Per column limits, by column position.
+     * @type ColumnSizing[]
+     */
+    columnSizing?: ColumnSizing[];
+    /** Called whenever a column is dragged or nudged to a new width.
+     * @type (e: Event, data: { index: number; width: number }) => void
+     */
+    onColumnResize?: (e: Event, data: {
+        index: number;
+        width: number;
+    }) => void;
+} & PolymorphicProps<Tag>;
+export type ColumnSizing = {
+    /** Narrowest the column may be dragged, in pixels.
+     * @default 40
+     */
+    minWidth?: number;
+    /** Width the column starts at, in pixels. Without it the browser sizes the column. */
+    defaultWidth?: number;
+};
+export type TableVirtualizer = {
+    /** Total number of real rows, the whole data set rather than the rendered window. */
+    size: number;
+    /** Scroll so the row at `index` renders. May be async. */
+    scrollToIndex?: (index: number) => void | Promise<void>;
+};
+/** @propsmith TableHeaderProps */
+export type TableHeaderProps<Tag extends 'thead' | 'div' = 'thead'> = {
+    /** The HTML element to render the header as. Inherited from the table by default.
+     * @type 'thead' | 'div'
+     * @default 'thead'
+     */
+    as?: Tag;
+    /** The DOM reference of the header element.
+     * @type HTMLTableSectionElement | HTMLDivElement
+     * @bindable
+     */
+    ref?: TableDOM[Tag] | HTMLDivElement;
+} & PolymorphicProps<Tag>;
+/** @propsmith TableHeaderCellProps */
+export type TableHeaderCellProps<Tag extends 'th' | 'div' = 'th'> = {
+    /** The HTML element to render the header cell as. Inherited from the table by default.
+     * @type 'th' | 'div'
+     * @default 'th'
+     */
+    as?: Tag;
+    /** The DOM reference of the header cell element.
+     * @type HTMLTableCellElement | HTMLDivElement
+     * @bindable
+     */
+    ref?: TableDOM[Tag] | HTMLDivElement;
+    /** Whether the column is sortable. Inherited from the table by default. */
+    sortable?: boolean;
+    /** The direction the column is currently sorted in. Also sets `aria-sort`. */
+    sortDirection?: SortDirection;
+    /** The indicator rendered next to the label of a sortable column.
+     * @type Snippet | Component
+     */
+    sortIcon?: Snippet<[{
+        class: string;
+    }]> | Component<{
+        class: string;
+    }>;
+    /** Content placed after the label, outside the sort button.
+     * @type Snippet | Component
+     */
+    aside?: Snippet<[{
+        class: string;
+    }]> | Component<{
+        class: string;
+    }>;
+    /** How the arrow keys treat the cell. `'group'` holds the focusable content of the cell out of
+     * the tab order until `Enter` steps in, and `Escape` steps back out. `'none'` skips the cell
+     * altogether. Only read when the table sets `enableTabspot`. A resizable header cell defaults to
+     * `'group'`, so the arrows reach its handle instead of leaving the column behind.
+     * @default 'cell'
+     */
+    focusMode?: CellFocusMode;
+    /** Whether the column can be resized. Inherited from the table by default. */
+    resizable?: boolean;
+    /** The accessible name of the resize handle. Give it a translated, and ideally per column, string
+     * — the attributes of the cell reach the cell, never the handle inside it.
+     * @default 'Resize column'
+     */
+    resizeLabel?: string;
+} & PolymorphicProps<Tag>;
+/** @propsmith TableBodyProps */
+export type TableBodyProps<Tag extends 'tbody' | 'div' = 'tbody'> = {
+    /** The HTML element to render the body as. Inherited from the table by default.
+     * @type 'tbody' | 'div'
+     * @default 'tbody'
+     */
+    as?: Tag;
+    /** The DOM reference of the body element.
+     * @type HTMLTableSectionElement | HTMLDivElement
+     * @bindable
+     */
+    ref?: TableDOM[Tag] | HTMLDivElement;
+} & PolymorphicProps<Tag>;
+/** @propsmith TableRowProps */
+export type TableRowProps<Tag extends 'tr' | 'div' = 'tr'> = {
+    /** The HTML element to render the row as. Inherited from the table by default.
+     * @type 'tr' | 'div'
+     * @default 'tr'
+     */
+    as?: Tag;
+    /** The DOM reference of the row element.
+     * @type HTMLTableRowElement | HTMLDivElement
+     * @bindable
+     */
+    ref?: TableDOM[Tag] | HTMLDivElement;
+    /** How the row is filled. Intended to mark a selected row.
+     * @default 'none'
+     */
+    appearance?: TableRowAppearance;
+} & PolymorphicProps<Tag>;
+/** @propsmith TableCellProps */
+export type TableCellProps<Tag extends 'td' | 'div' = 'td'> = {
+    /** The HTML element to render the cell as. Inherited from the table by default.
+     * @type 'td' | 'div'
+     * @default 'td'
+     */
+    as?: Tag;
+    /** The DOM reference of the cell element.
+     * @type HTMLTableCellElement | HTMLDivElement
+     * @bindable
+     */
+    ref?: TableDOM[Tag] | HTMLDivElement;
+    /** How the arrow keys treat the cell. `'group'` holds the focusable content of the cell out of
+     * the tab order until `Enter` steps in, and `Escape` steps back out. `'none'` skips the cell
+     * altogether. Only read when the table sets `enableTabspot`.
+     * @default 'cell'
+     */
+    focusMode?: CellFocusMode;
+} & PolymorphicProps<Tag>;
+/** @propsmith TableSelectionCellProps */
+export type TableSelectionCellProps<Tag extends 'td' | 'div' = 'td'> = {
+    /** The HTML element to render the cell as. Inherited from the table by default.
+     * @type 'td' | 'div'
+     * @default 'td'
+     */
+    as?: Tag;
+    /** The DOM reference of the cell element.
+     * @type HTMLTableCellElement | HTMLDivElement
+     * @bindable
+     */
+    ref?: TableDOM[Tag] | HTMLDivElement;
+    /** A table can have two kinds of selection modes.
+     * @default 'checkbox'
+     */
+    type?: SelectionType;
+    /** Whether the row is selected. `'mixed'` renders the indeterminate state.
+     * @type boolean | 'mixed'
+     * @default false
+     */
+    checked?: boolean | 'mixed';
+    /** Only shows the indicator when it is checked, or the row is hovered or focused.
+     * @default false
+     */
+    subtle?: boolean;
+    /** Hides the indicator while it keeps taking up the same space.
+     * @default false
+     */
+    invisible?: boolean;
+    /** The props to spread on the checkbox rendered when `type` is `'checkbox'`.
+     * @type CheckboxProps
+     */
+    checkboxIndicator?: Omit<CheckboxProps<'div'>, 'wrapperAs' | 'checked' | 'indeterminate' | 'children'>;
+    /** The props to spread on the radio button rendered when `type` is `'radio'`.
+     * @type RadioButtonProps
+     */
+    radioIndicator?: Omit<RadioButtonProps, 'checked' | 'group'>;
+} & PolymorphicProps<Tag>;
+/** @propsmith TableCellLayoutProps */
+export type TableCellLayoutProps = {
+    /** The DOM reference of the layout element.
+     * @bindable
+     */
+    ref?: HTMLDivElement;
+    /** An icon, an avatar or any other visual element placed before the main content.
+     * @type Snippet | Component
+     */
+    media?: Snippet<[{
+        class: string;
+    }]> | Component<{
+        class: string;
+    }>;
+    /** A second line of text that describes or complements the main content. */
+    description?: string;
+    /** Emphasizes the cell by enlarging the media and bolding the main content. */
+    appearance?: 'primary';
+    /** Clips the content with an ellipsis instead of letting it wrap. */
+    truncate?: boolean;
+} & PolymorphicProps<'div'>;
+/** @propsmith TableCellActionsProps */
+export type TableCellActionsProps = {
+    /** The DOM reference of the actions element.
+     * @bindable
+     */
+    ref?: HTMLDivElement;
+    /** Keeps the actions on screen instead of waiting for the row to be hovered or focused. */
+    visible?: boolean;
+} & PolymorphicProps<'div'>;
+export type TableContextConfig = {
+    size: TableSize;
+    noNativeElements: boolean;
+    sortable: boolean;
+    enableTabspot: boolean;
+    resizableColumns: boolean;
+};
+export type TableContextState = {
+    columnWidths: number[];
+};
+export type TableContextMethods = {
+    /** The width a column should render at, or `undefined` to let the browser decide. */
+    getColumnWidth: (index: number) => number | undefined;
+    /** Records a new width for a column, clamped to the minimum it was given. */
+    resizeColumn: (e: Event, index: number, width: number) => void;
+};
+export type TableContext = FSContext<TableContextConfig, TableContextState, null, TableContextMethods>;

package/dist/components/table/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.