@sveltia/ui 0.54.0 → 0.55.0

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

@@ -0,0 +1,126 @@
+export default Tree;
+type Tree = {
+    $on?(type: string, callback: (e: any) => void): () => void;
+    $set?(props: Partial<KeyboardEventHandlers & MouseEventHandlers & PointerEventHandlers & FocusEventHandlers & DragEventHandlers & Props & Record<string, any>>): void;
+};
+/**
+ * A tree view widget that displays a hierarchical list of items, which can be expanded, collapsed
+ * and selected.
+ * @see https://w3c.github.io/aria/#tree
+ * @see https://www.w3.org/WAI/ARIA/apg/patterns/treeview/
+ */
+declare const Tree: import("svelte").Component<import("../../typedefs").KeyboardEventHandlers & import("../../typedefs").MouseEventHandlers & import("../../typedefs").PointerEventHandlers & import("../../typedefs").FocusEventHandlers & import("../../typedefs").DragEventHandlers & {
+    /**
+     * A reference to the wrapper element.
+     */
+    element?: HTMLElement | undefined;
+    /**
+     * The `class` attribute on the wrapper element.
+     */
+    class?: string | undefined;
+    /**
+     * Whether to hide the widget. An alias of the `aria-hidden`
+     * attribute.
+     */
+    hidden?: boolean | undefined;
+    /**
+     * Whether to disable the widget. An alias of the `aria-disabled`
+     * attribute.
+     */
+    disabled?: boolean | undefined;
+    /**
+     * Whether to make the widget read-only. An alias of the
+     * `aria-readonly` attribute.
+     */
+    readonly?: boolean | undefined;
+    /**
+     * Whether to allow selecting more than one `<TreeItem>`. An alias
+     * of the `aria-multiselectable` attribute.
+     */
+    multiple?: boolean | undefined;
+    /**
+     * Whether to select an item by clicking on it.
+     */
+    clickToSelect?: boolean | undefined;
+    /**
+     * Whether to select an item as soon as it receives
+     * focus. Default: `true` on a single-select tree, `false` on a multi-select tree.
+     */
+    selectionFollowsFocus?: boolean | undefined;
+    /**
+     * Whether to expand or collapse a parent item when the item
+     * itself, rather than its chevron, is clicked or activated with the Enter key.
+     */
+    expandOnSelect?: boolean | undefined;
+    /**
+     * The `aria-label` attribute on the wrapper element. Required
+     * unless the `aria-labelledby` attribute is provided.
+     */
+    ariaLabel?: string | undefined;
+    /**
+     * Primary slot content.
+     */
+    children?: Snippet<[]> | undefined;
+    /**
+     * Custom `Change` event handler.
+     */
+    onChange?: ((event: CustomEvent) => void) | undefined;
+} & Record<string, any>, {}, "element">;
+type Props = {
+    /**
+     * A reference to the wrapper element.
+     */
+    element?: HTMLElement | undefined;
+    /**
+     * The `class` attribute on the wrapper element.
+     */
+    class?: string | undefined;
+    /**
+     * Whether to hide the widget. An alias of the `aria-hidden`
+     * attribute.
+     */
+    hidden?: boolean | undefined;
+    /**
+     * Whether to disable the widget. An alias of the `aria-disabled`
+     * attribute.
+     */
+    disabled?: boolean | undefined;
+    /**
+     * Whether to make the widget read-only. An alias of the
+     * `aria-readonly` attribute.
+     */
+    readonly?: boolean | undefined;
+    /**
+     * Whether to allow selecting more than one `<TreeItem>`. An alias
+     * of the `aria-multiselectable` attribute.
+     */
+    multiple?: boolean | undefined;
+    /**
+     * Whether to select an item by clicking on it.
+     */
+    clickToSelect?: boolean | undefined;
+    /**
+     * Whether to select an item as soon as it receives
+     * focus. Default: `true` on a single-select tree, `false` on a multi-select tree.
+     */
+    selectionFollowsFocus?: boolean | undefined;
+    /**
+     * Whether to expand or collapse a parent item when the item
+     * itself, rather than its chevron, is clicked or activated with the Enter key.
+     */
+    expandOnSelect?: boolean | undefined;
+    /**
+     * The `aria-label` attribute on the wrapper element. Required
+     * unless the `aria-labelledby` attribute is provided.
+     */
+    ariaLabel?: string | undefined;
+    /**
+     * Primary slot content.
+     */
+    children?: Snippet<[]> | undefined;
+    /**
+     * Custom `Change` event handler.
+     */
+    onChange?: ((event: CustomEvent) => void) | undefined;
+};
+import type { Snippet } from 'svelte';

package/dist/components/util/app-shell.svelte

@@ -250,6 +250,13 @@
   --sui-listbox-border-color: var(--sui-control-border-color);
   --sui-listbox-foreground-color: var(--sui-control-foreground-color);
   --sui-listbox-background-color: hsl(var(--sui-background-color-1-hsl));
+  --sui-tree-border-radius: var(--sui-control-medium-border-radius);
+  --sui-tree-border-color: var(--sui-control-border-color);
+  --sui-tree-foreground-color: var(--sui-control-foreground-color);
+  --sui-tree-background-color: hsl(var(--sui-background-color-1-hsl));
+  --sui-tree-item-border-radius: var(--sui-control-medium-border-radius);
+  --sui-tree-item-height: var(--sui-control-medium-height);
+  --sui-tree-item-indent: 16px;
   --sui-textbox-border-radius: var(--sui-control-medium-border-radius);
   --sui-textbox-height: var(--sui-control-medium-height);
   --sui-textbox-border-color: var(--sui-control-border-color);

package/dist/index.d.ts

@@ -72,6 +72,8 @@ export { default as TextArea } from "./components/text-field/text-area.svelte";
 export { default as TextInput } from "./components/text-field/text-input.svelte";
 export { default as Toast } from "./components/toast/toast.svelte";
 export { default as Toolbar } from "./components/toolbar/toolbar.svelte";
+export { default as TreeItem } from "./components/tree/tree-item.svelte";
+export { default as Tree } from "./components/tree/tree.svelte";
 export { default as TruncatedText } from "./components/typography/truncated-text.svelte";
 export { default as AppShell } from "./components/util/app-shell.svelte";
 export { default as EmptyState } from "./components/util/empty-state.svelte";

package/dist/index.js

@@ -72,6 +72,8 @@ export { default as TextArea } from './components/text-field/text-area.svelte';
 export { default as TextInput } from './components/text-field/text-input.svelte';
 export { default as Toast } from './components/toast/toast.svelte';
 export { default as Toolbar } from './components/toolbar/toolbar.svelte';
+export { default as TreeItem } from './components/tree/tree-item.svelte';
+export { default as Tree } from './components/tree/tree.svelte';
 export { default as TruncatedText } from './components/typography/truncated-text.svelte';
 export { default as AppShell } from './components/util/app-shell.svelte';
 export { default as EmptyState } from './components/util/empty-state.svelte';

package/dist/services/tree.svelte.d.ts

@@ -0,0 +1,235 @@
+/**
+ * Implement keyboard and mouse interactions for the `tree` composite widget, following the ARIA
+ * Tree View pattern. Unlike the other composite widgets handled by the `Group` class, a tree
+ * manages the focus (roving `tabindex`) and the selection separately, and it also supports
+ * expanding and collapsing parent nodes.
+ * @see https://www.w3.org/WAI/ARIA/apg/patterns/treeview/
+ */
+export class Tree {
+    /**
+     * Initialize a new `Tree` instance.
+     * @param {HTMLElement} parent Parent element.
+     * @param {object} [options] Options.
+     * @param {boolean} [options.clickToSelect] Whether to select an item by clicking on it.
+     * @param {boolean} [options.selectionFollowsFocus] Whether to select an item as soon as it
+     * receives focus. Default: `true` on a single-select tree, `false` on a multi-select tree.
+     * @param {boolean} [options.expandOnSelect] Whether to expand or collapse a parent item when the
+     * item itself, rather than its chevron, is clicked or activated.
+     */
+    constructor(parent: HTMLElement, { clickToSelect, selectionFollowsFocus, expandOnSelect }?: {
+        clickToSelect?: boolean | undefined;
+        selectionFollowsFocus?: boolean | undefined;
+        expandOnSelect?: boolean | undefined;
+    } | undefined);
+    parent: HTMLElement;
+    id: string;
+    clickToSelect: boolean;
+    expandOnSelect: boolean;
+    /**
+     * Whether the selection follows the focus. `undefined` means auto detect.
+     * @type {boolean | undefined}
+     */
+    selectionFollowsFocusOption: boolean | undefined;
+    /**
+     * Item used as the starting point of a range selection.
+     * @type {HTMLElement | undefined}
+     */
+    anchor: HTMLElement | undefined;
+    /**
+     * Currently accumulated type-ahead search terms.
+     * @type {string}
+     */
+    typeAheadTerms: string;
+    /**
+     * Timer used to reset the type-ahead search terms.
+     * @type {ReturnType<typeof globalThis.setTimeout> | undefined}
+     */
+    typeAheadTimer: ReturnType<typeof globalThis.setTimeout> | undefined;
+    /** @type {(event: MouseEvent) => void} */
+    _onClick: (event: MouseEvent) => void;
+    /** @type {(event: KeyboardEvent) => void} */
+    _onKeyDown: (event: KeyboardEvent) => void;
+    /** @type {(event: FocusEvent) => void} */
+    _onFocusIn: (event: FocusEvent) => void;
+    observer: MutationObserver;
+    /**
+     * Activate the items.
+     */
+    activate(): void;
+    /**
+     * Whether more than one item can be selected.
+     * @type {boolean}
+     */
+    get multi(): boolean;
+    /**
+     * Whether an item is selected as soon as it receives focus.
+     * @type {boolean}
+     */
+    get selectionFollowsFocus(): boolean;
+    /**
+     * Whether the widget is disabled.
+     * @type {boolean}
+     */
+    get isDisabled(): boolean;
+    /**
+     * Whether the widget is read-only.
+     * @type {boolean}
+     */
+    get isReadOnly(): boolean;
+    /**
+     * List of all the items, including the ones within a collapsed parent, in document order.
+     * @type {HTMLElement[]}
+     */
+    get allItems(): HTMLElement[];
+    /**
+     * List of the items that are not hidden, either explicitly or by a collapsed ancestor.
+     * @type {HTMLElement[]}
+     */
+    get visibleItems(): HTMLElement[];
+    /**
+     * List of the items that can receive focus.
+     * @type {HTMLElement[]}
+     */
+    get activeItems(): HTMLElement[];
+    /**
+     * List of the selected items.
+     * @type {HTMLElement[]}
+     */
+    get selectedItems(): HTMLElement[];
+    /**
+     * Item that is currently in the tab order, which is the item that has or last had focus.
+     * @type {HTMLElement | undefined}
+     */
+    get currentItem(): HTMLElement | undefined;
+    /**
+     * Get the group element that contains the child items of the given item.
+     * @param {HTMLElement} item Parent item.
+     * @returns {HTMLElement | undefined} Group element, if the item has one.
+     */
+    getGroup(item: HTMLElement): HTMLElement | undefined;
+    /**
+     * Get the child items of the given item.
+     * @param {HTMLElement} item Parent item.
+     * @returns {HTMLElement[]} Child items. Empty if the item is a leaf node.
+     */
+    getChildItems(item: HTMLElement): HTMLElement[];
+    /**
+     * Get the items directly owned by the given group, ignoring any deeper descendants.
+     * @param {HTMLElement} group Group element or the widget root.
+     * @returns {HTMLElement[]} Child items.
+     */
+    getItemsInGroup(group: HTMLElement): HTMLElement[];
+    /**
+     * Get the parent item of the given item.
+     * @param {HTMLElement} item Item.
+     * @returns {HTMLElement | undefined} Parent item, if the item is not at the root level.
+     */
+    getParentItem(item: HTMLElement): HTMLElement | undefined;
+    /**
+     * Whether the given item is a parent node that can be expanded and collapsed.
+     * @param {HTMLElement} item Item.
+     * @returns {boolean} Result.
+     */
+    isParent(item: HTMLElement): boolean;
+    /**
+     * Whether the given parent item is expanded.
+     * @param {HTMLElement} item Item.
+     * @returns {boolean} Result.
+     */
+    isExpanded(item: HTMLElement): boolean;
+    /**
+     * Whether any of the ancestors of the given item is collapsed, meaning the item is not displayed.
+     * @param {HTMLElement} item Item.
+     * @returns {boolean} Result.
+     */
+    hasCollapsedAncestor(item: HTMLElement): boolean;
+    /**
+     * Get the text label of the given item, which is used for the type-ahead search.
+     * @param {HTMLElement} item Item.
+     * @returns {string} Label.
+     */
+    getLabel(item: HTMLElement): string;
+    /**
+     * Assign the element IDs, positional attributes and roving `tabindex` to the items. Called
+     * whenever the items are added or removed.
+     */
+    update(): void;
+    /**
+     * Scroll the given element into view if needed.
+     * @param {HTMLElement} element Element to be scrolled into view.
+     */
+    scrollIntoView(element: HTMLElement): void;
+    /**
+     * Move focus to the given item.
+     * @param {HTMLElement} item Item to be focused.
+     * @param {object} [options] Options.
+     * @param {boolean} [options.select] Whether to also select the item. Default: depends on the
+     * `selectionFollowsFocus` option.
+     */
+    focusItem(item: HTMLElement, { select }?: {
+        select?: boolean | undefined;
+    } | undefined): void;
+    /**
+     * Update the selection state of the given item, and notify the change if needed.
+     * @param {HTMLElement} item Item.
+     * @param {boolean} selected Whether to select the item.
+     */
+    setSelected(item: HTMLElement, selected: boolean): void;
+    /**
+     * Select the given item.
+     * @param {HTMLElement} item Item to be selected.
+     * @param {object} [options] Options.
+     * @param {boolean} [options.additive] Whether to toggle the item without deselecting the other
+     * items. Multi-select only.
+     * @param {boolean} [options.range] Whether to select all the items between the anchor and the
+     * given item. Multi-select only.
+     */
+    selectItem(item: HTMLElement, { additive, range }?: {
+        additive?: boolean | undefined;
+        range?: boolean | undefined;
+    } | undefined): void;
+    /**
+     * Select all the items that are currently displayed. Multi-select only.
+     * @param {HTMLElement} item Item that triggered the action.
+     */
+    selectAll(item: HTMLElement): void;
+    /**
+     * Expand or collapse the given parent item.
+     * @param {HTMLElement} item Item to be expanded or collapsed.
+     * @param {boolean} expanded Whether to expand the item.
+     */
+    expandItem(item: HTMLElement, expanded: boolean): void;
+    /**
+     * Expand all the sibling parent items at the same level as the given item.
+     * @param {HTMLElement} item Item.
+     */
+    expandSiblings(item: HTMLElement): void;
+    /**
+     * Move focus to the next item that matches the accumulated type-ahead search terms.
+     * @param {string} char Typed character.
+     * @param {HTMLElement} currentItem Currently focused item.
+     */
+    typeAhead(char: string, currentItem: HTMLElement): void;
+    /**
+     * Handle the `focusin` event on the widget. Make the newly focused item the only one in the tab
+     * order, so that Shift+Tab and Tab move focus out of the widget.
+     * @param {FocusEvent} event `focusin` event.
+     */
+    onFocusIn(event: FocusEvent): void;
+    /**
+     * Handle the `click` event on the widget.
+     * @param {MouseEvent} event `click` event.
+     */
+    onClick(event: MouseEvent): void;
+    /**
+     * Handle the `keydown` event on the widget.
+     * @param {KeyboardEvent} event `keydown` event.
+     */
+    onKeyDown(event: KeyboardEvent): void;
+    /**
+     * Clean up event listeners.
+     */
+    destroy(): void;
+}
+export function activateTree(params?: object | undefined): Attachment;
+import type { Attachment } from 'svelte/attachments';