@w5-ui/svelte 0.6.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@w5-ui/svelte",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Svelte 5 components for the Dash UI design system - mirrors the @w5-ui/react API 1:1. Part of Webber's design systems.",
   "keywords": [
     "svelte",
@@ -45,7 +45,7 @@
   },
   "dependencies": {
     "@w5-ui/assets": "^0.2.1",
-    "@w5-ui/tokens": "^0.5.0"
+    "@w5-ui/tokens": "^0.7.0"
   },
   "devDependencies": {
     "svelte": "^5.56.4",

package/src/lib/components/TreeBrowser.svelte

@@ -0,0 +1,281 @@
+<script module lang="ts">
+  export type {
+    TreeBrowserCollection,
+    TreeBrowserItem,
+    TreeBrowserData,
+    TreeBrowserNodeType,
+    FlatNode,
+  } from './tree-browser-model.ts'
+  export { topLevelIds } from './tree-browser-model.ts'
+  export type { TreeBrowserRowContext } from './TreeBrowserNode.svelte'
+</script>
+
+<!--
+  TreeBrowser - a folder/file tree modelled on instructure-ui's
+  `ui-tree-browser` (TreeBrowser v2), medium size, `folderTree` variant.
+
+  ## Data model
+  instructure-ui shape: id-keyed `collections` (folders) + id-keyed
+  `items` (leaves) + a `rootId`. The root collection is structural (its
+  own row is never drawn); its `collections` then `items` become the
+  top-level rows. Folders always render before items within a level.
+
+  ## Visual mapping (instructure medium/folderTree -> @w5-ui/tokens)
+  Both motifs (dark + light) resolve through the token variables below,
+  so the component needs no motif branching.
+
+  | instructure-ui (medium/folderTree) | @w5-ui token / utility            |
+  | ---------------------------------- | --------------------------------- |
+  | `baseSpacingMedium` row indent     | nested `ul` `pl-3` (12px = space-3)|
+  | row min height                     | `min-h-8` (32px)                  |
+  | row horizontal padding             | `px-2` (8px = space-2)            |
+  | `iconsMarginRightMedium`           | `gap-2` (8px = space-2)           |
+  | name font size (medium)            | `text-13` (--fs-13)               |
+  | descriptor font size               | `text-11` (--fs-11), `text-text-4`|
+  | folderTree `before` connector      | nested `ul` `border-l border-border-2` |
+  | text colour (resting / selected)   | `text-text-2` / `text-text-1`     |
+  | hover state                        | `bg-row-hover`                    |
+  | selected state                     | `bg-brand-05/[0.18]`              |
+  | focus ring                         | `--focus-ring` (`:focus-visible`) |
+
+  ## Expansion
+  Uncontrolled via `defaultExpanded`, or controlled via `expanded` +
+  `ontoggle`. `topLevelIds(collections, rootId)` (exported) lets a
+  consumer expand only the top level in one line.
+
+  ## Accessibility
+  `role="tree"` on the list, `role="treeitem"` / `role="group"` on rows
+  and nested lists, `aria-expanded` / `aria-selected`, roving tabindex,
+  and full Arrow/Home/End/Enter/Space keyboard navigation. Fixed row
+  heights keep expansion CLS-free; the caret rotation respects
+  `prefers-reduced-motion`.
+-->
+<script lang="ts">
+  import { tick, type Snippet } from 'svelte'
+  import TreeBrowserNode, { type TreeBrowserRowContext } from './TreeBrowserNode.svelte'
+  import {
+    childIds,
+    flattenVisible,
+    hasChildren,
+    type TreeBrowserCollection,
+    type TreeBrowserItem,
+    type TreeBrowserNodeType,
+  } from './tree-browser-model.ts'
+
+  interface Props {
+    collections?: Record<string, TreeBrowserCollection>;
+    items?: Record<string, TreeBrowserItem>;
+    rootId?: string;
+    /** Uncontrolled initial expansion. Ignored when `expanded` is set. */
+    defaultExpanded?: string[];
+    /** Controlled expansion set. When provided, pair with `ontoggle`. */
+    expanded?: string[] | undefined;
+    ontoggle?: ((id: string) => void) | undefined;
+    selected?: string | undefined;
+    onselect?: ((id: string, type: TreeBrowserNodeType) => void) | undefined;
+    /** Reserved for future small/large sizes. Only medium is implemented. */
+    size?: 'medium';
+    variant?: 'folderTree' | 'indent';
+    label?: string | undefined;
+    /** Per-row leading icon that overrides the built-in folder/file glyphs. */
+    itemIcon?: Snippet<[TreeBrowserRowContext]>;
+    /** Trailing badge (missing-file marker, count, etc.). */
+    badge?: Snippet<[TreeBrowserRowContext]>;
+    className?: string;
+  }
+
+  let {
+    collections = {},
+    items = {},
+    rootId = 'root',
+    defaultExpanded = [],
+    expanded = undefined,
+    ontoggle = undefined,
+    selected = $bindable(undefined),
+    onselect = undefined,
+    size: _size = 'medium',
+    variant = 'folderTree',
+    label = undefined,
+    itemIcon = undefined,
+    badge = undefined,
+    className = '',
+  }: Props = $props()
+
+  const isControlled = $derived(expanded !== undefined)
+
+  // svelte-ignore state_referenced_locally
+  let internalExpanded = $state(new Set<string>(defaultExpanded))
+  let expandedSet = $derived(isControlled ? new Set(expanded) : internalExpanded)
+
+  let data = $derived({ collections, items, rootId })
+  let rootChildren = $derived(childIds(collections, rootId))
+  let flat = $derived(flattenVisible(data, expandedSet))
+
+  // svelte-ignore state_referenced_locally
+  let focusedId = $state(flattenVisible({ collections, items, rootId }, new Set(defaultExpanded))[0]?.id ?? '')
+  let rootEl = $state<HTMLUListElement | undefined>(undefined)
+
+  function setExpanded(id: string, next: boolean) {
+    if (isControlled) {
+      ontoggle?.(id)
+      return
+    }
+    if (next) internalExpanded.add(id)
+    else internalExpanded.delete(id)
+    internalExpanded = new Set(internalExpanded)
+  }
+
+  function toggle(id: string) {
+    setExpanded(id, !expandedSet.has(id))
+  }
+
+  function select(id: string, type: TreeBrowserNodeType) {
+    selected = id
+    focusedId = id
+    onselect?.(id, type)
+  }
+
+  async function moveFocus(id: string) {
+    focusedId = id
+    await tick()
+    rootEl?.querySelector<HTMLElement>(`[data-tree-id="${cssEscape(id)}"]`)?.focus()
+  }
+
+  function cssEscape(value: string): string {
+    return typeof CSS !== 'undefined' && CSS.escape ? CSS.escape(value) : value.replace(/"/g, '\\"')
+  }
+
+  function nodeType(el: Element): TreeBrowserNodeType {
+    return el.getAttribute('data-type') === 'collection' ? 'collection' : 'item'
+  }
+
+  function handleFocusin(e: FocusEvent) {
+    const el = (e.target as HTMLElement).closest('[data-tree-id]')
+    if (el) focusedId = el.getAttribute('data-tree-id') ?? focusedId
+  }
+
+  function handleClick(e: MouseEvent) {
+    const row = (e.target as HTMLElement).closest('.w5-tb__row')
+    if (!row) return
+    const el = row.closest('[data-tree-id]')
+    if (!el) return
+    const id = el.getAttribute('data-tree-id')
+    if (!id) return
+    const type = nodeType(el)
+    select(id, type)
+    if (type === 'collection' && hasChildren(collections, id)) toggle(id)
+  }
+
+  function handleKeydown(e: KeyboardEvent) {
+    const el = (e.target as HTMLElement).closest('[data-tree-id]')
+    if (!el) return
+    const id = el.getAttribute('data-tree-id')
+    if (!id) return
+    const type = nodeType(el)
+
+    const idx = flat.findIndex((n) => n.id === id)
+    const current = flat[idx]
+    const nodeHasChildren = !!current?.hasChildren
+    const isNodeExpanded = expandedSet.has(id)
+
+    switch (e.key) {
+      case 'ArrowDown': {
+        e.preventDefault()
+        const next = flat[idx + 1]
+        if (next) moveFocus(next.id)
+        break
+      }
+      case 'ArrowUp': {
+        e.preventDefault()
+        const prev = flat[idx - 1]
+        if (prev) moveFocus(prev.id)
+        break
+      }
+      case 'ArrowRight': {
+        e.preventDefault()
+        if (nodeHasChildren && !isNodeExpanded) toggle(id)
+        else if (nodeHasChildren && isNodeExpanded) {
+          const first = firstChildId(id)
+          if (first) moveFocus(first)
+        }
+        break
+      }
+      case 'ArrowLeft': {
+        e.preventDefault()
+        if (nodeHasChildren && isNodeExpanded) toggle(id)
+        else if (current?.parentId && current.parentId !== rootId) moveFocus(current.parentId)
+        break
+      }
+      case 'Home': {
+        e.preventDefault()
+        if (flat[0]) moveFocus(flat[0].id)
+        break
+      }
+      case 'End': {
+        e.preventDefault()
+        const last = flat[flat.length - 1]
+        if (last) moveFocus(last.id)
+        break
+      }
+      case 'Enter':
+      case ' ': {
+        e.preventDefault()
+        select(id, type)
+        if (type === 'collection' && nodeHasChildren) toggle(id)
+        break
+      }
+    }
+  }
+
+  function firstChildId(id: string): string | undefined {
+    const { collections: c, items: i } = childIds(collections, id)
+    return c[0] ?? i[0]
+  }
+</script>
+
+<ul
+  bind:this={rootEl}
+  role="tree"
+  aria-label={label}
+  data-variant={variant}
+  class={`w5-tb m-0 list-none p-0 text-text-2 ${className}`}
+  onkeydown={handleKeydown}
+  onfocusin={handleFocusin}
+  onclick={handleClick}
+>
+  {#each rootChildren.collections as id (id)}
+    <TreeBrowserNode
+      {id}
+      type="collection"
+      {data}
+      expanded={expandedSet}
+      {selected}
+      {focusedId}
+      {variant}
+      {itemIcon}
+      {badge}
+    />
+  {/each}
+  {#each rootChildren.items as id (id)}
+    <TreeBrowserNode
+      {id}
+      type="item"
+      {data}
+      expanded={expandedSet}
+      {selected}
+      {focusedId}
+      {variant}
+      {itemIcon}
+      {badge}
+    />
+  {/each}
+</ul>
+<!--
+  NOTE: This component is intentionally STYLE-LESS (Tailwind utilities
+  only, no `<style>` block). The assistant dashboard serves
+  `@w5-ui/svelte` as raw source (not prebundled); a `<style>` block
+  there emits a `?type=style` virtual module that `@tailwindcss/vite`
+  mis-parses ("Invalid declaration"). The focus ring is therefore
+  expressed via the `group-focus-visible/tb` utilities in
+  TreeBrowserNode instead of a scoped `:global` rule.
+-->

package/src/lib/components/TreeBrowserNode.svelte

@@ -0,0 +1,169 @@
+<script module lang="ts">
+  import type { Snippet } from 'svelte'
+  import type {
+    TreeBrowserData,
+    TreeBrowserNodeType,
+  } from './tree-browser-model.ts'
+
+  export interface TreeBrowserRowContext {
+    id: string
+    type: TreeBrowserNodeType
+    name: string
+  }
+
+  export interface TreeBrowserNodeProps {
+    id: string
+    type: TreeBrowserNodeType
+    data: TreeBrowserData
+    expanded: Set<string>
+    selected: string | undefined
+    focusedId: string
+    variant: 'folderTree' | 'indent'
+    itemIcon?: Snippet<[TreeBrowserRowContext]>
+    badge?: Snippet<[TreeBrowserRowContext]>
+  }
+</script>
+
+<script lang="ts">
+  import TreeBrowserNode from './TreeBrowserNode.svelte'
+  import { childIds, hasChildren } from './tree-browser-model.ts'
+
+  let {
+    id,
+    type,
+    data,
+    expanded,
+    selected,
+    focusedId,
+    variant,
+    itemIcon,
+    badge,
+  }: TreeBrowserNodeProps = $props()
+
+  let node = $derived(
+    type === 'collection' ? data.collections[id] : data.items?.[id],
+  )
+  let name = $derived(node?.name ?? '')
+  let descriptor = $derived(node?.descriptor)
+  let isCollection = $derived(type === 'collection')
+  let nodeHasChildren = $derived(isCollection && hasChildren(data.collections, id))
+  let isExpanded = $derived(expanded.has(id))
+  let isSelected = $derived(selected === id)
+  let children = $derived(isCollection ? childIds(data.collections, id) : { collections: [], items: [] })
+  let rowContext = $derived({ id, type, name } as TreeBrowserRowContext)
+</script>
+
+<li
+  role="treeitem"
+  aria-expanded={nodeHasChildren ? isExpanded : undefined}
+  aria-selected={isSelected}
+  tabindex={focusedId === id ? 0 : -1}
+  data-tree-id={id}
+  data-type={type}
+  class="w5-tb__item group/tb list-none outline-none focus:outline-none focus-visible:outline-none"
+>
+  <div
+    data-selected={isSelected ? 'true' : undefined}
+    class="w5-tb__row flex min-h-8 cursor-pointer select-none items-center gap-2 rounded px-2 text-13 text-text-2 hover:bg-row-hover group-focus-visible/tb:[outline:var(--focus-ring)] group-focus-visible/tb:[outline-offset:-2px] data-[selected=true]:bg-brand-05/[0.18] data-[selected=true]:text-text-1"
+  >
+    {#if nodeHasChildren}
+      <svg
+        viewBox="0 0 12 12"
+        fill="none"
+        aria-hidden="true"
+        class="h-3 w-3 shrink-0 text-text-4 transition-transform duration-100 motion-reduce:transition-none {isExpanded ? 'rotate-90' : ''}"
+      >
+        <path
+          d="M4 2l4 4-4 4"
+          stroke="currentColor"
+          stroke-width="1.5"
+          stroke-linecap="round"
+          stroke-linejoin="round"
+        />
+      </svg>
+    {:else}
+      <span class="inline-block w-3 shrink-0" aria-hidden="true"></span>
+    {/if}
+
+    <span class="w5-tb__icon flex h-4 w-4 shrink-0 items-center justify-center text-text-4">
+      {#if itemIcon}
+        {@render itemIcon(rowContext)}
+      {:else if isCollection}
+        <svg viewBox="0 0 16 16" fill="none" aria-hidden="true" class="h-4 w-4">
+          {#if isExpanded}
+            <path
+              d="M1.5 5.5h13l-1.6 7A1 1 0 0 1 11.9 13H3.4a1 1 0 0 1-1-.8L1 4.2a1 1 0 0 1 1-1.2h3.2a1 1 0 0 1 .8.4l.9 1.2H13a1 1 0 0 1 1 1v.9"
+              stroke="currentColor"
+              stroke-width="1.2"
+              stroke-linejoin="round"
+            />
+          {:else}
+            <path
+              d="M1.5 3.8a1 1 0 0 1 1-1h3.2a1 1 0 0 1 .8.4l.9 1.2h6.1a1 1 0 0 1 1 1v6.3a1 1 0 0 1-1 1H2.5a1 1 0 0 1-1-1V3.8Z"
+              stroke="currentColor"
+              stroke-width="1.2"
+              stroke-linejoin="round"
+            />
+          {/if}
+        </svg>
+      {:else}
+        <svg viewBox="0 0 16 16" fill="none" aria-hidden="true" class="h-4 w-4">
+          <path
+            d="M4 1.5h5L13 5.5v9a1 1 0 0 1-1 1H4a1 1 0 0 1-1-1v-12a1 1 0 0 1 1-1Z"
+            stroke="currentColor"
+            stroke-width="1.2"
+            stroke-linejoin="round"
+          />
+          <path d="M9 1.5v4h4" stroke="currentColor" stroke-width="1.2" stroke-linejoin="round" />
+        </svg>
+      {/if}
+    </span>
+
+    <span class="w5-tb__names flex min-w-0 flex-1 flex-col justify-center leading-tight">
+      <span class="w5-tb__name truncate">{name}</span>
+      {#if descriptor}
+        <span class="w5-tb__descriptor truncate text-11 text-text-4">{descriptor}</span>
+      {/if}
+    </span>
+
+    {#if badge}
+      <span class="w5-tb__badge ml-auto shrink-0">{@render badge(rowContext)}</span>
+    {/if}
+  </div>
+
+  {#if isCollection && nodeHasChildren && isExpanded}
+    <ul
+      role="group"
+      class="w5-tb__group m-0 list-none pl-3 {variant === 'folderTree'
+        ? 'ml-[11px] border-l border-border-2'
+        : 'ml-2'}"
+    >
+      {#each children.collections as childId (childId)}
+        <TreeBrowserNode
+          id={childId}
+          type="collection"
+          {data}
+          {expanded}
+          {selected}
+          {focusedId}
+          {variant}
+          {itemIcon}
+          {badge}
+        />
+      {/each}
+      {#each children.items as itemId (itemId)}
+        <TreeBrowserNode
+          id={itemId}
+          type="item"
+          {data}
+          {expanded}
+          {selected}
+          {focusedId}
+          {variant}
+          {itemIcon}
+          {badge}
+        />
+      {/each}
+    </ul>
+  {/if}
+</li>

package/src/lib/components/tree-browser-model.ts

@@ -0,0 +1,111 @@
+/**
+ * Pure data model + helpers for {@link TreeBrowser} (instructure-ui
+ * `ui-tree-browser` shape). Kept framework-free so the React and Web
+ * Component mirrors reuse the exact same walking / keyboard logic.
+ *
+ * A tree is an id-keyed map of `collections` (folders) plus an id-keyed
+ * map of `items` (leaves) and a `rootId`. The root collection is a
+ * structural container: its own row is never rendered, only its
+ * children become the top-level rows.
+ */
+
+export interface TreeBrowserCollection {
+  id: string
+  name: string
+  /** Small secondary line shown under the name (instructure descriptor). */
+  descriptor?: string
+  /** Child collection ids, in render order (folders render before items). */
+  collections?: string[]
+  /** Child item ids, in render order. */
+  items?: string[]
+}
+
+export interface TreeBrowserItem {
+  id: string
+  name: string
+  descriptor?: string
+}
+
+export type TreeBrowserNodeType = 'collection' | 'item'
+
+/** A single visible (i.e. not hidden by a collapsed ancestor) row. */
+export interface FlatNode {
+  id: string
+  type: TreeBrowserNodeType
+  depth: number
+  hasChildren: boolean
+  parentId: string | undefined
+}
+
+export interface TreeBrowserData {
+  collections: Record<string, TreeBrowserCollection>
+  items?: Record<string, TreeBrowserItem>
+  rootId: string
+}
+
+/**
+ * The ids of the root collection's direct child collections + items -
+ * exactly the rows a consumer expands to satisfy "top level only".
+ */
+export function topLevelIds(
+  collections: Record<string, TreeBrowserCollection>,
+  rootId: string,
+): string[] {
+  const root = collections[rootId]
+  if (!root) return []
+  return [...(root.collections ?? []), ...(root.items ?? [])]
+}
+
+/** Ordered child ids of a collection: nested folders first, then items. */
+export function childIds(
+  collections: Record<string, TreeBrowserCollection>,
+  id: string,
+): { collections: string[]; items: string[] } {
+  const node = collections[id]
+  return { collections: node?.collections ?? [], items: node?.items ?? [] }
+}
+
+/** Whether a collection has any children (folders or items). */
+export function hasChildren(
+  collections: Record<string, TreeBrowserCollection>,
+  id: string,
+): boolean {
+  const { collections: c, items } = childIds(collections, id)
+  return c.length > 0 || items.length > 0
+}
+
+/**
+ * Depth-first flatten of the currently VISIBLE rows, honouring the
+ * `expanded` set. Cycle-safe (a collection referenced twice, or a
+ * self/loop reference, is visited once). Used for roving-tabindex
+ * keyboard navigation.
+ */
+export function flattenVisible(data: TreeBrowserData, expanded: ReadonlySet<string>): FlatNode[] {
+  const out: FlatNode[] = []
+  const seen = new Set<string>([data.rootId])
+
+  const walk = (collectionId: string, depth: number): void => {
+    const { collections, items } = childIds(data.collections, collectionId)
+    for (const childId of collections) {
+      if (seen.has(childId)) continue
+      seen.add(childId)
+      const childHasChildren = hasChildren(data.collections, childId)
+      out.push({
+        id: childId,
+        type: 'collection',
+        depth,
+        hasChildren: childHasChildren,
+        parentId: collectionId,
+      })
+      if (childHasChildren && expanded.has(childId)) walk(childId, depth + 1)
+    }
+    for (const itemId of items) {
+      if (seen.has(itemId)) continue
+      seen.add(itemId)
+      out.push({ id: itemId, type: 'item', depth, hasChildren: false, parentId: collectionId })
+    }
+  }
+
+  walk(data.rootId, 0)
+  return out
+}

package/src/lib/index.ts

@@ -75,6 +75,16 @@ export type { ComboboxOption } from './components/Combobox.svelte'
 export { default as Drawer } from './components/Drawer.svelte'
 export { default as TreeView } from './components/TreeView.svelte'
 export type { TreeNode } from './components/TreeView.svelte'
+export { default as TreeBrowser, topLevelIds } from './components/TreeBrowser.svelte'
+export type {
+  TreeBrowserCollection,
+  TreeBrowserItem,
+  TreeBrowserData,
+  TreeBrowserNodeType,
+  TreeBrowserRowContext,
+  FlatNode,
+} from './components/TreeBrowser.svelte'
+export { childIds, hasChildren, flattenVisible } from './components/tree-browser-model.ts'
 export { default as DatePicker } from './components/DatePicker.svelte'
 export { default as CommandPalette } from './components/CommandPalette.svelte'
 export type { CommandItem } from './components/CommandPalette.svelte'