@spaethtech/svelte-ui 0.21.1-dev.130.6593aa4 → 0.21.1-dev.132.b812036

package/dist/components/FileList/FileList.svelte

@@ -0,0 +1,354 @@
+<!--
+/**
+ * FileList — the details pane of a file explorer: Name · Date modified · Type · Size, folders first,
+ * sortable by any column. Click selects (Ctrl/⌘ adds, Shift extends), double-click or Enter opens,
+ * right-click reports what's under the pointer (the event bubbles on, so a wrapping svelte-ui
+ * `ContextMenu` opens), and desktop files dragged in are handed to `ondropfiles` (onto a folder row →
+ * that folder). Keys: Delete, F2 (rename in place), Backspace (up), Ctrl+A, arrows.
+ *
+ * Consumer-driven: the PARENT owns the data and every action (via callbacks); this component owns only
+ * selection, sort, the in-place rename field, and the drop highlight. Unlike `DataTable` this is shaped
+ * like an OS explorer (fixed explorer columns that collapse by container width), not a generic grid.
+ * See FileList.spec.md.
+ */
+-->
+<script lang="ts" module>
+  export type { ExplorerEntry, FileListColumn } from "./types.js";
+  export { formatSize } from "./types.js";
+</script>
+
+<script lang="ts">
+  import { untrack } from "svelte";
+  import Badge from "../Badge/Badge.svelte";
+  import Input from "../Input.svelte";
+  import { uiI18n } from "../../i18n.js";
+  import { variantToken, type Variant } from "../../types/variants.js";
+  import IconFolder from "~icons/mdi/folder";
+  import IconFile from "~icons/mdi/file-outline";
+  import IconDrive from "~icons/mdi/harddisk";
+  import IconUp from "~icons/mdi/menu-up";
+  import IconDown from "~icons/mdi/menu-down";
+  import { formatSize, type ExplorerEntry, type FileListColumn } from "./types.js";
+
+  const i18n = uiI18n();
+
+  let {
+    entries,
+    loading = false,
+    error = null,
+    selected = $bindable(new Set<string>()),
+    editing = $bindable<string | null>(null),
+    sortCol = $bindable<FileListColumn>("name"),
+    sortDir = $bindable<1 | -1>(1),
+    emptyText,
+    canDrop = true,
+    variant = "primary",
+    formatDate,
+    class: cls = "",
+    onopen,
+    oncontextmenu,
+    ondropfiles,
+    ondelete,
+    onrename,
+    oncommitname,
+    onup,
+    onsort,
+  }: {
+    entries: ExplorerEntry[];
+    loading?: boolean;
+    error?: string | null;
+    /** Selected keys (bindable). */
+    selected?: Set<string>;
+    /** The entry being renamed in place (bindable), or null. */
+    editing?: string | null;
+    /** Active sort column / direction (bindable; `onsort` also fires on change). */
+    sortCol?: FileListColumn;
+    sortDir?: 1 | -1;
+    /** Empty-state text. Default: localized "This folder is empty." */
+    emptyText?: string;
+    canDrop?: boolean;
+    /** Selection accent (shared axis). Default `primary`. */
+    variant?: Variant;
+    /** Override the Date column formatting. Default: `Intl.DateTimeFormat(i18n.locale)` medium+short. */
+    formatDate?: (modified: string) => string;
+    class?: string;
+    onopen: (e: ExplorerEntry) => void;
+    /** Right-click: `entry` is the row under the pointer, or null on empty space. Not prevented — a
+     *  wrapping `ContextMenu` still opens. */
+    oncontextmenu?: (ev: MouseEvent, entry: ExplorerEntry | null) => void;
+    ondropfiles?: (files: File[], into: ExplorerEntry | null) => void;
+    ondelete?: (entries: ExplorerEntry[]) => void;
+    onrename?: (entry: ExplorerEntry) => void;
+    /** An in-place rename ended — `name` null = cancelled/unchanged. */
+    oncommitname?: (entry: ExplorerEntry, name: string | null) => void;
+    onup?: () => void;
+    /** Fired when the sort column/direction changes (e.g. to persist or sort server-side). */
+    onsort?: (col: FileListColumn, dir: 1 | -1) => void;
+  } = $props();
+
+  const token = $derived(variantToken[variant]);
+  const empty = $derived(emptyText ?? i18n.messages.emptyFolder);
+
+  const defaultFormatDate = (iso: string) =>
+    new Intl.DateTimeFormat(i18n.locale, {
+      year: "numeric",
+      month: "short",
+      day: "numeric",
+      hour: "2-digit",
+      minute: "2-digit",
+    }).format(new Date(iso));
+  const fmtDate = (iso: string) => (formatDate ? formatDate(iso) : defaultFormatDate(iso));
+
+  /** "File folder", "PDF file", "Local disk" — the Type column (localized). */
+  function typeLabel(e: ExplorerEntry): string {
+    if (e.kind === "drive") return i18n.messages.localDisk;
+    if (e.kind === "folder") return i18n.messages.fileFolder;
+    const dot = e.name.lastIndexOf(".");
+    return dot > 0
+      ? i18n.messages.fileOfType({ ext: e.name.slice(dot + 1).toUpperCase() })
+      : i18n.messages.genericFile;
+  }
+
+  let draft = $state("");
+  // field starts from the current name — only when editing starts, not on every live listing
+  $effect(() => {
+    const k = editing;
+    if (k) untrack(() => (draft = entries.find((e) => e.key === k)?.name ?? ""));
+  });
+  function finish(e: ExplorerEntry, commit: boolean) {
+    if (editing !== e.key) return;
+    editing = null;
+    const name = draft.trim();
+    oncommitname?.(e, commit && name && name !== e.name ? name : null);
+  }
+  /** Focus the field and select the name without its extension, as a desktop explorer does. */
+  function editField(node: HTMLElement, e: ExplorerEntry) {
+    const input = node.querySelector("input");
+    if (input) {
+      input.focus();
+      const dot = e.kind === "file" ? e.name.lastIndexOf(".") : -1;
+      input.setSelectionRange(0, dot > 0 ? dot : e.name.length);
+    }
+  }
+
+  let anchor = $state<string | null>(null);
+  let dropOn = $state<string | null>(null); // a folder key, or "" for the pane
+
+  const rank = (e: ExplorerEntry) => (e.kind === "file" ? 1 : 0);
+  const sorted = $derived(
+    [...entries].sort((a, b) => {
+      if (rank(a) !== rank(b)) return rank(a) - rank(b);
+      let c = 0;
+      if (sortCol === "size") c = (a.size ?? -1) - (b.size ?? -1);
+      else if (sortCol === "modified")
+        c = String(a.modified ?? "").localeCompare(String(b.modified ?? ""));
+      else if (sortCol === "type") c = typeLabel(a).localeCompare(typeLabel(b));
+      if (c === 0)
+        c = a.name.localeCompare(b.name, i18n.locale, { numeric: true, sensitivity: "base" });
+      return c * sortDir;
+    }),
+  );
+  const picked = $derived(sorted.filter((e) => selected.has(e.key)));
+
+  function sortBy(c: FileListColumn) {
+    if (sortCol === c) sortDir = sortDir === 1 ? -1 : 1;
+    else {
+      sortCol = c;
+      sortDir = 1;
+    }
+    onsort?.(sortCol, sortDir);
+  }
+
+  function click(ev: MouseEvent, e: ExplorerEntry) {
+    if (ev.shiftKey && anchor) {
+      const keys = sorted.map((x) => x.key);
+      const [a, b] = [keys.indexOf(anchor), keys.indexOf(e.key)].sort((x, y) => x - y);
+      selected = new Set(keys.slice(a, b + 1));
+      return;
+    }
+    if (ev.ctrlKey || ev.metaKey) {
+      const s = new Set(selected);
+      if (s.has(e.key)) s.delete(e.key);
+      else s.add(e.key);
+      selected = s;
+    } else selected = new Set([e.key]);
+    anchor = e.key;
+  }
+  // A right-click bubbles on (so a wrapping ContextMenu opens where the pointer is); the row's handler
+  // runs first and marks the event so the pane's handler doesn't also fire for empty space.
+  const ROW = Symbol("row");
+  function context(ev: MouseEvent, e: ExplorerEntry | null) {
+    if (!oncontextmenu) return;
+    if (!e && (ev as unknown as Record<symbol, boolean>)[ROW]) return;
+    if (e) (ev as unknown as Record<symbol, boolean>)[ROW] = true;
+    if (e && !selected.has(e.key)) {
+      selected = new Set([e.key]);
+      anchor = e.key;
+    }
+    if (!e) selected = new Set();
+    oncontextmenu(ev, e);
+  }
+
+  function onkeydown(ev: KeyboardEvent) {
+    if ((ev.target as HTMLElement).closest("input")) return;
+    const keys = sorted.map((x) => x.key);
+    const i = anchor ? keys.indexOf(anchor) : -1;
+    if (ev.key === "ArrowDown" || ev.key === "ArrowUp") {
+      const n = Math.max(0, Math.min(keys.length - 1, i + (ev.key === "ArrowDown" ? 1 : -1)));
+      if (keys[n]) {
+        anchor = keys[n];
+        selected = new Set([keys[n]]);
+        document.getElementById(rowId(keys[n]))?.scrollIntoView({ block: "nearest" });
+      }
+    } else if (ev.key === "Enter" && picked.length === 1) onopen(picked[0]);
+    else if (ev.key === "Delete" && picked.length && ondelete) ondelete(picked);
+    else if (ev.key === "F2" && picked.length === 1) {
+      if (oncommitname) editing = picked[0].key;
+      else onrename?.(picked[0]);
+    } else if (ev.key === "Backspace" && onup) onup();
+    else if (ev.key === "a" && (ev.ctrlKey || ev.metaKey)) selected = new Set(keys);
+    else if (ev.key === "Escape") selected = new Set();
+    else return;
+    ev.preventDefault();
+  }
+
+  const hasFiles = (ev: DragEvent) => !!ev.dataTransfer?.types.includes("Files");
+  function over(ev: DragEvent, target: string) {
+    if (!canDrop || !ondropfiles || !hasFiles(ev)) return;
+    ev.preventDefault();
+    ev.stopPropagation();
+    if (ev.dataTransfer) ev.dataTransfer.dropEffect = "copy";
+    dropOn = target;
+  }
+  function drop(ev: DragEvent, into: ExplorerEntry | null) {
+    if (!canDrop || !ondropfiles || !hasFiles(ev)) return;
+    ev.preventDefault();
+    ev.stopPropagation();
+    dropOn = null;
+    const files = Array.from(ev.dataTransfer?.files ?? []);
+    if (files.length) ondropfiles(files, into);
+  }
+
+  const rowId = (key: string) =>
+    `fl-${btoa(unescape(encodeURIComponent(key))).replace(/[^A-Za-z0-9]/g, "")}`;
+  const muted = "[color:color-mix(in_srgb,var(--ui-color-text)_60%,transparent)]";
+  // columns follow the LIST's own width (it sits beside a tree): Name + Size, then Date, then Type
+  const cols =
+    "grid grid-cols-[minmax(0,1fr)_6rem] @lg:grid-cols-[minmax(0,1fr)_11rem_6rem] @2xl:grid-cols-[minmax(0,1fr)_11rem_8rem_6rem] gap-x-4 items-center";
+</script>
+
+{#snippet head(c: FileListColumn, label: string, extra = "")}
+  <span
+    role="columnheader"
+    class={extra}
+    aria-sort={sortCol === c ? (sortDir === 1 ? "ascending" : "descending") : "none"}
+  >
+    <span
+      role="button"
+      tabindex="0"
+      class="inline-flex cursor-pointer items-center gap-0.5 hover:underline"
+      onclick={() => sortBy(c)}
+      onkeydown={(e) => (e.key === "Enter" || e.key === " ") && (e.preventDefault(), sortBy(c))}
+      >{label}{#if sortCol === c}{#if sortDir === 1}<IconUp class="size-4" />{:else}<IconDown
+            class="size-4"
+          />{/if}{/if}</span
+    >
+  </span>
+{/snippet}
+
+<!-- svelte-ignore a11y_no_noninteractive_tabindex a11y_no_noninteractive_element_interactions -->
+<div
+  role="grid"
+  aria-multiselectable="true"
+  aria-label={i18n.messages.files}
+  tabindex="0"
+  class="@container flex h-full min-h-0 flex-col select-none outline-none {cls}
+    {dropOn === '' ? `ring-2 ring-inset [--tw-ring-color:var(${token})]` : ''}"
+  {onkeydown}
+  oncontextmenu={(ev) => context(ev, null)}
+  ondragover={(ev) => over(ev, "")}
+  ondragleave={(ev) => {
+    if (!(ev.currentTarget as HTMLElement).contains(ev.relatedTarget as Node)) dropOn = null;
+  }}
+  ondrop={(ev) => drop(ev, null)}
+  onclick={(ev) => {
+    if (ev.target === ev.currentTarget) selected = new Set();
+  }}
+>
+  <div
+    role="row"
+    class="{cols} border-b px-3 py-2 font-medium [border-color:var(--ui-border-color)] {muted}"
+  >
+    {@render head("name", i18n.messages.colName)}
+    {@render head("modified", i18n.messages.colDateModified, "hidden @lg:block")}
+    {@render head("type", i18n.messages.colType, "hidden @2xl:block")}
+    {@render head("size", i18n.messages.colSize, "text-right")}
+  </div>
+  <div class="min-h-0 grow overflow-y-auto py-1" role="rowgroup">
+    {#if error}
+      <div class="px-3 py-6 [color:var(--ui-color-error)]">{error}</div>
+    {:else if loading && entries.length === 0}
+      <div class="px-3 py-6 {muted}">{i18n.messages.loading}</div>
+    {:else if entries.length === 0}
+      <div class="px-3 py-6 {muted}">{empty}</div>
+    {:else}
+      {#each sorted as e (e.key)}
+        {@const isSel = selected.has(e.key)}
+        <!-- svelte-ignore a11y_click_events_have_key_events a11y_no_static_element_interactions -->
+        <div
+          id={rowId(e.key)}
+          role="row"
+          aria-selected={isSel}
+          tabindex="-1"
+          class="{cols} mx-1 cursor-default rounded px-3 py-1.5
+            {isSel
+            ? `[background-color:color-mix(in_srgb,var(${token})_16%,transparent)]`
+            : dropOn === e.key
+              ? `[background-color:color-mix(in_srgb,var(${token})_10%,transparent)] ring-1 ring-inset [--tw-ring-color:var(${token})]`
+              : 'hover:[background-color:var(--ui-color-hover)]'}"
+          onclick={(ev) => click(ev, e)}
+          ondblclick={() => onopen(e)}
+          oncontextmenu={(ev) => context(ev, e)}
+          ondragover={e.kind === "file" ? undefined : (ev) => over(ev, e.key)}
+          ondrop={e.kind === "file" ? undefined : (ev) => drop(ev, e)}
+        >
+          <span role="gridcell" class="flex min-w-0 items-center gap-2">
+            {#if e.kind === "drive"}
+              <IconDrive class="size-5 shrink-0 {muted}" />
+            {:else if e.kind === "folder"}
+              <IconFolder class="size-5 shrink-0 [color:var(--ui-color-warning)]" />
+            {:else}
+              <IconFile class="size-5 shrink-0 {muted}" />
+            {/if}
+            {#if editing === e.key}
+              <!-- svelte-ignore a11y_no_static_element_interactions -->
+              <div
+                class="min-w-0 grow"
+                use:editField={e}
+                onclick={(ev) => ev.stopPropagation()}
+                ondblclick={(ev) => ev.stopPropagation()}
+                onkeydown={(ev) => {
+                  if (ev.key === "Enter") (ev.preventDefault(), finish(e, true));
+                  else if (ev.key === "Escape") (ev.preventDefault(), finish(e, false));
+                }}
+                onfocusout={() => finish(e, true)}
+              >
+                <Input bind:value={draft} aria-label={i18n.messages.newName} />
+              </div>
+            {:else}
+              <span class="truncate">{e.name}</span>
+            {/if}
+            {#each e.flags ?? [] as f (f)}<Badge size="sm" variant="neutral" text={f} />{/each}
+          </span>
+          <span role="gridcell" class="hidden truncate @lg:block {muted}"
+            >{e.modified ? fmtDate(e.modified) : ""}</span
+          >
+          <span role="gridcell" class="hidden truncate @2xl:block {muted}">{typeLabel(e)}</span>
+          <span role="gridcell" class="truncate text-right {muted}"
+            >{e.kind === "file" ? formatSize(e.size, i18n.locale) : ""}</span
+          >
+        </div>
+      {/each}
+    {/if}
+  </div>
+</div>

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

@@ -0,0 +1,39 @@
+export type { ExplorerEntry, FileListColumn } from "./types.js";
+export { formatSize } from "./types.js";
+import { type Variant } from "../../types/variants.js";
+import { type ExplorerEntry, type FileListColumn } from "./types.js";
+type $$ComponentProps = {
+    entries: ExplorerEntry[];
+    loading?: boolean;
+    error?: string | null;
+    /** Selected keys (bindable). */
+    selected?: Set<string>;
+    /** The entry being renamed in place (bindable), or null. */
+    editing?: string | null;
+    /** Active sort column / direction (bindable; `onsort` also fires on change). */
+    sortCol?: FileListColumn;
+    sortDir?: 1 | -1;
+    /** Empty-state text. Default: localized "This folder is empty." */
+    emptyText?: string;
+    canDrop?: boolean;
+    /** Selection accent (shared axis). Default `primary`. */
+    variant?: Variant;
+    /** Override the Date column formatting. Default: `Intl.DateTimeFormat(i18n.locale)` medium+short. */
+    formatDate?: (modified: string) => string;
+    class?: string;
+    onopen: (e: ExplorerEntry) => void;
+    /** Right-click: `entry` is the row under the pointer, or null on empty space. Not prevented — a
+     *  wrapping `ContextMenu` still opens. */
+    oncontextmenu?: (ev: MouseEvent, entry: ExplorerEntry | null) => void;
+    ondropfiles?: (files: File[], into: ExplorerEntry | null) => void;
+    ondelete?: (entries: ExplorerEntry[]) => void;
+    onrename?: (entry: ExplorerEntry) => void;
+    /** An in-place rename ended — `name` null = cancelled/unchanged. */
+    oncommitname?: (entry: ExplorerEntry, name: string | null) => void;
+    onup?: () => void;
+    /** Fired when the sort column/direction changes (e.g. to persist or sort server-side). */
+    onsort?: (col: FileListColumn, dir: 1 | -1) => void;
+};
+declare const FileList: import("svelte").Component<$$ComponentProps, {}, "selected" | "editing" | "sortCol" | "sortDir">;
+type FileList = ReturnType<typeof FileList>;
+export default FileList;

package/dist/components/FileList/index.d.ts

@@ -0,0 +1,3 @@
+export { default as FileList } from "./FileList.svelte";
+export type { ExplorerEntry, FileListColumn } from "./types.js";
+export { formatSize } from "./types.js";

package/dist/components/FileList/index.js

@@ -0,0 +1,2 @@
+export { default as FileList } from "./FileList.svelte";
+export { formatSize } from "./types.js";

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

@@ -0,0 +1,16 @@
+/** Shapes for the `FileList` details view. Backend-agnostic — the consumer owns the data. */
+export interface ExplorerEntry {
+    /** Unique key — usually the full path. */
+    key: string;
+    name: string;
+    kind: "drive" | "folder" | "file";
+    size?: number | null;
+    /** ISO date string (or anything `new Date()` accepts); formatted for the Date column. */
+    modified?: string | null;
+    /** Small `Badge`s rendered after the name ("read-only", …). */
+    flags?: string[];
+}
+/** The sortable columns. */
+export type FileListColumn = "name" | "modified" | "type" | "size";
+/** Human size — `1.5 MB`. The numeric part is localized via `locale` (decimal separator). */
+export declare function formatSize(n: number | null | undefined, locale?: string): string;

package/dist/components/FileList/types.js

@@ -0,0 +1,17 @@
+/** Shapes for the `FileList` details view. Backend-agnostic — the consumer owns the data. */
+/** Human size — `1.5 MB`. The numeric part is localized via `locale` (decimal separator). */
+export function formatSize(n, locale) {
+    if (n === null || n === undefined)
+        return "";
+    const u = ["B", "KB", "MB", "GB", "TB"];
+    let i = 0;
+    let v = n;
+    while (v >= 1024 && i < u.length - 1) {
+        v /= 1024;
+        i++;
+    }
+    const num = i
+        ? new Intl.NumberFormat(locale, { maximumFractionDigits: 1 }).format(v)
+        : String(v);
+    return `${num} ${u[i]}`;
+}

package/dist/components/SideBarMenu/SideBarMenu.svelte

@@ -95,8 +95,9 @@
     link?: string;
     badge?: SideBarMenuBadge;
     /** Child items — rendered as a fly-out popout. Recursive: a child that itself has children
-     *  cascades into a further popout (or steps deeper in `stepped` mode). */
-    children?: SideBarMenuItem[];
+     *  cascades into a further popout (or steps deeper in `stepped` mode). May include
+     *  `{ divider: true }` entries to draw a separator between children. */
+    children?: SideBarMenuEntry[];
     /** Action row (no `link`) — renders a `<button>` and calls this on click. For a "toggle"
      *  row (an AI panel, etc.) or a non-navigating action. Runs after the drawer/popout reset. */
     onclick?: (e: MouseEvent) => void;
@@ -114,6 +115,20 @@
      *  the default `currentPath` segment-boundary match against `link`. */
     activeMatch?: SideBarMenuActiveRule;
   };
+
+  /**
+   * A horizontal rule between adjacent rows in an `items` / `bottomItems` / `children` list — a 1px
+   * full-bleed separator (`--ui-border-color`) drawn between the two rows it sits between. It adds no
+   * navigable row and (visually) only the 1px line, so it never disturbs the fixed-height row rhythm.
+   * Leading, trailing, and consecutive dividers collapse — a divider renders ONLY between two real
+   * rows. Honoured identically in the fly-out popout, the stepped sub-view, and the inline
+   * expanded/drawer rail. Use the discriminated form `{ divider: true }` so a genuinely malformed item
+   * still falls through to the visible "malformed item" row rather than silently becoming a separator.
+   */
+  export type SideBarMenuDivider = { divider: true };
+
+  /** A SideBarMenu list entry: either a {@link SideBarMenuItem} or a {@link SideBarMenuDivider}. */
+  export type SideBarMenuEntry = SideBarMenuItem | SideBarMenuDivider;
 </script>
 
 <script lang="ts">
@@ -159,8 +174,8 @@
     class: additionalClass = "",
     ...rest
   }: {
-    items?: SideBarMenuItem[];
-    bottomItems?: SideBarMenuItem[];
+    items?: SideBarMenuEntry[];
+    bottomItems?: SideBarMenuEntry[];
     currentPath: string;
     size?: Size;
     /**
@@ -492,7 +507,34 @@
   // reserving group that lack an icon still get an empty box so everything aligns. The main rail counts
   // `items` + `bottomItems` as ONE group (so top/bottom align); each popout / stepped sub-view is its
   // own group.
-  const anyIcon = (list: SideBarMenuItem[]) => list.some((i) => i.icon || i.badge);
+  // ── Dividers ────────────────────────────────────────────────────
+  // A list entry is either a real item or a `{ divider: true }` separator. Dividers are not navigable
+  // rows — they render as a 1px full-bleed rule BETWEEN two real rows (see `renderRows`).
+  const isDivider = (e: SideBarMenuEntry): e is SideBarMenuDivider =>
+    typeof e === "object" && e !== null && (e as SideBarMenuDivider).divider === true;
+  const itemsOnly = (list: SideBarMenuEntry[] = []): SideBarMenuItem[] =>
+    list.filter((e): e is SideBarMenuItem => !isDivider(e));
+
+  // Normalize a list into the rows to render, each tagged with whether a divider precedes it. Leading,
+  // trailing, and consecutive dividers collapse — `dividerBefore` is set only when a divider sits
+  // between two real rows. `index` is the entry's ORIGINAL position in the list, so open-path ids
+  // (`top:3`, `id>5`) stay stable and unique no matter how many dividers precede a row.
+  type RenderRow = { item: SideBarMenuItem; index: number; dividerBefore: boolean };
+  function renderRows(list: SideBarMenuEntry[] = []): RenderRow[] {
+    const out: RenderRow[] = [];
+    let pending = false;
+    list.forEach((e, index) => {
+      if (isDivider(e)) {
+        if (out.length > 0) pending = true; // drop leading; collapse runs of dividers
+        return;
+      }
+      out.push({ item: e, index, dividerBefore: pending });
+      pending = false;
+    });
+    return out; // a trailing divider is never consumed → dropped
+  }
+
+  const anyIcon = (list: SideBarMenuEntry[] = []) => itemsOnly(list).some((i) => i.icon || i.badge);
   const railReserve = $derived(anyIcon(items) || anyIcon(bottomItems));
 
   // ── Mobile drawer state ─────────────────────────────────────────
@@ -605,7 +647,8 @@
     } else if (item.link && pathMatches(item.link, currentPath)) {
       return true;
     }
-    if (item.children?.length) return item.children.some(isItemActive);
+    const kids = itemsOnly(item.children);
+    if (kids.length) return kids.some(isItemActive);
     return false;
   }
   // A row's OWN active state (drives `aria-current`) — its own rule/link only, never descendants.
@@ -919,7 +962,7 @@
   {@const active = isItemActive(item)}
   {@const ownActive = isItemOwnActive(item)}
   {@const reserveIcon = opts.reserveIcon ?? true}
-  {@const hasChildren = (item.children?.length ?? 0) > 0}
+  {@const hasChildren = itemsOnly(item.children).length > 0}
   {@const isParent = hasChildren || !!item.popout}
   {@const hasLink = !!item.link}
   {@const isOpen = !!opts.id && isOnPath(opts.id)}
@@ -1028,7 +1071,7 @@
   depth: number,
 )}
   {@render row(item, { id, isPopoutChild: depth > 0, reserveIcon })}
-  {#if (((item.children?.length ?? 0) > 0) || !!item.popout) && !isStepped}
+  {#if (itemsOnly(item.children).length > 0 || !!item.popout) && !isStepped}
     {@const top = depth === 0}
     {@const geom = top
       ? geometryFor(id, group)
@@ -1085,9 +1128,9 @@
 {#snippet popoutPanel(item: SideBarMenuItem, id: ItemId, group: "top" | "bottom", maxHeight: string)}
   {@const popoutId = popoutDomId(id)}
   {@const isOpen = isOnPath(id)}
-  {@const kids = item.children ?? []}
-  {@const win = popoutWindow(id, kids.length)}
-  {@const childReserve = anyIcon(kids)}
+  {@const rows = renderRows(item.children)}
+  {@const win = popoutWindow(id, rows.length)}
+  {@const childReserve = anyIcon(item.children)}
   {@const rowsShown = (win.up ? 1 : 0) + (win.end - win.start) + (win.down ? 1 : 0)}
   {@const bd = popoutBorder(id, group, !id.includes(">"), rowsShown)}
   <!-- Nav submenu popout — a list of links (NOT role="menu"); Tab navigates, per the disclosure-nav
@@ -1106,7 +1149,7 @@
       : (e) => {
           if (win.up || win.down) {
             e.preventDefault();
-            stepPopout(id, kids.length, Math.sign(e.deltaY) * 3);
+            stepPopout(id, rows.length, Math.sign(e.deltaY) * 3);
           }
         }}
     onkeydown={item.popout
@@ -1114,10 +1157,10 @@
       : (e) => {
           if (e.key === "ArrowDown") {
             e.preventDefault();
-            stepPopout(id, kids.length, 1);
+            stepPopout(id, rows.length, 1);
           } else if (e.key === "ArrowUp") {
             e.preventDefault();
-            stepPopout(id, kids.length, -1);
+            stepPopout(id, rows.length, -1);
           }
         }}
   >
@@ -1129,15 +1172,20 @@
         {@render item.popout()}
       </div>
     {:else}
-      {#if win.up}{@render arrowRow(id, kids.length, -1)}{/if}
+      {#if win.up}{@render arrowRow(id, rows.length, -1)}{/if}
       <ul class="flex flex-col">
-        {#each kids.slice(win.start, win.end) as child, i (child.label)}
+        {#each rows.slice(win.start, win.end) as r, i (r.index)}
+          <!-- A divider renders only BETWEEN real rows: suppress it at the window's top edge (i===0),
+               where there's nothing above it and it would collide with the panel border. -->
+          {#if r.dividerBefore && i > 0}
+            <li class="list-none border-t [border-color:var(--ui-border-color)]" role="separator"></li>
+          {/if}
           <li class="list-none">
-            {@render menuNode(child, `${id}>${win.start + i}`, group, childReserve, 1)}
+            {@render menuNode(r.item, `${id}>${r.index}`, group, childReserve, 1)}
           </li>
         {/each}
       </ul>
-      {#if win.down}{@render arrowRow(id, kids.length, 1)}{/if}
+      {#if win.down}{@render arrowRow(id, rows.length, 1)}{/if}
     {/if}
   </div>
 {/snippet}
@@ -1203,20 +1251,29 @@
 		     return here — there is no in-drawer back row by design so
 		     the back affordance stays in a single, consistent spot. -->
     {@const currentParent = stepPath[stepPath.length - 1]}
-    {@const stepReserve = anyIcon(currentParent.children ?? [])}
+    {@const stepRows = renderRows(currentParent.children)}
+    {@const stepReserve = anyIcon(currentParent.children)}
     <ul class="flex flex-col {scrollList}">
-      {#each currentParent.children ?? [] as child, ci (child.label)}
+      {#each stepRows as r, i (r.index)}
+        {#if r.dividerBefore && i > 0}
+          <li class="list-none border-t [border-color:var(--ui-border-color)]" role="separator"></li>
+        {/if}
         <li class="list-none">
-          {@render row(child, { id: `step:${ci}`, isPopoutChild: true, reserveIcon: stepReserve })}
+          {@render row(r.item, { id: `step:${r.index}`, isPopoutChild: true, reserveIcon: stepReserve })}
         </li>
       {/each}
     </ul>
   {:else}
-    {#if items.length > 0}
+    {@const topRows = renderRows(items)}
+    {@const bottomRows = renderRows(bottomItems)}
+    {#if topRows.length > 0}
       <ul class="flex flex-col {scrollList}">
-        {#each items as item, idx (item.label)}
+        {#each topRows as r, i (r.index)}
+          {#if r.dividerBefore && i > 0}
+            <li class="list-none border-t [border-color:var(--ui-border-color)]" role="separator"></li>
+          {/if}
           <li class="list-none">
-            {@render menuNode(item, `top:${idx}`, "top", railReserve, 0)}
+            {@render menuNode(r.item, `top:${r.index}`, "top", railReserve, 0)}
           </li>
         {/each}
       </ul>
@@ -1224,15 +1281,18 @@
 
     <!-- With items present, the scrollable top list (flex-1) already fills the gap; only add a spacer
          to push the bottom cluster down when there are no top items. -->
-    {#if items.length === 0 && bottomItems.length > 0}
+    {#if topRows.length === 0 && bottomRows.length > 0}
       <div class="flex-1"></div>
     {/if}
 
-    {#if bottomItems.length > 0}
+    {#if bottomRows.length > 0}
       <ul class="flex flex-col shrink-0">
-        {#each bottomItems as item, idx (item.label)}
+        {#each bottomRows as r, i (r.index)}
+          {#if r.dividerBefore && i > 0}
+            <li class="list-none border-t [border-color:var(--ui-border-color)]" role="separator"></li>
+          {/if}
           <li class="list-none">
-            {@render menuNode(item, `bottom:${idx}`, "bottom", railReserve, 0)}
+            {@render menuNode(r.item, `bottom:${r.index}`, "bottom", railReserve, 0)}
           </li>
         {/each}
       </ul>

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

@@ -75,8 +75,9 @@ export type SideBarMenuItem = {
     link?: string;
     badge?: SideBarMenuBadge;
     /** Child items — rendered as a fly-out popout. Recursive: a child that itself has children
-     *  cascades into a further popout (or steps deeper in `stepped` mode). */
-    children?: SideBarMenuItem[];
+     *  cascades into a further popout (or steps deeper in `stepped` mode). May include
+     *  `{ divider: true }` entries to draw a separator between children. */
+    children?: SideBarMenuEntry[];
     /** Action row (no `link`) — renders a `<button>` and calls this on click. For a "toggle"
      *  row (an AI panel, etc.) or a non-navigating action. Runs after the drawer/popout reset. */
     onclick?: (e: MouseEvent) => void;
@@ -94,14 +95,28 @@ export type SideBarMenuItem = {
      *  the default `currentPath` segment-boundary match against `link`. */
     activeMatch?: SideBarMenuActiveRule;
 };
+/**
+ * A horizontal rule between adjacent rows in an `items` / `bottomItems` / `children` list — a 1px
+ * full-bleed separator (`--ui-border-color`) drawn between the two rows it sits between. It adds no
+ * navigable row and (visually) only the 1px line, so it never disturbs the fixed-height row rhythm.
+ * Leading, trailing, and consecutive dividers collapse — a divider renders ONLY between two real
+ * rows. Honoured identically in the fly-out popout, the stepped sub-view, and the inline
+ * expanded/drawer rail. Use the discriminated form `{ divider: true }` so a genuinely malformed item
+ * still falls through to the visible "malformed item" row rather than silently becoming a separator.
+ */
+export type SideBarMenuDivider = {
+    divider: true;
+};
+/** A SideBarMenu list entry: either a {@link SideBarMenuItem} or a {@link SideBarMenuDivider}. */
+export type SideBarMenuEntry = SideBarMenuItem | SideBarMenuDivider;
 import type { HTMLAttributes } from "svelte/elements";
 import type { Size } from "../../types/sizes.js";
 import { type Variant } from "../../types/variants.js";
 import { type Breakpoint } from "../../types/breakpoints.js";
 type ModesMap = Partial<Record<Breakpoint, SideBarMenuMode>>;
 type $$ComponentProps = {
-    items?: SideBarMenuItem[];
-    bottomItems?: SideBarMenuItem[];
+    items?: SideBarMenuEntry[];
+    bottomItems?: SideBarMenuEntry[];
     currentPath: string;
     size?: Size;
     /**

package/dist/i18n.d.ts

@@ -62,6 +62,19 @@ export type UiMessages = {
     removeFile: MsgFn<{
         name: string;
     }>;
+    files: Msg;
+    colName: Msg;
+    colDateModified: Msg;
+    colType: Msg;
+    colSize: Msg;
+    emptyFolder: Msg;
+    newName: Msg;
+    localDisk: Msg;
+    fileFolder: Msg;
+    genericFile: Msg;
+    fileOfType: MsgFn<{
+        ext: string;
+    }>;
     queryHelp: Msg;
     querySyntax: Msg;
     casts: Msg;

package/dist/i18n.js

@@ -53,6 +53,17 @@ export const defaultUiMessages = {
     textAreaControls: "Text area with controls",
     uploadFiles: "Upload files: drag and drop or activate to browse",
     removeFile: ({ name }) => `Remove ${name}`,
+    files: "Files",
+    colName: "Name",
+    colDateModified: "Date modified",
+    colType: "Type",
+    colSize: "Size",
+    emptyFolder: "This folder is empty.",
+    newName: "New name",
+    localDisk: "Local disk",
+    fileFolder: "File folder",
+    genericFile: "File",
+    fileOfType: ({ ext }) => `${ext} file`,
     queryHelp: "Query help",
     querySyntax: "Query syntax",
     casts: "Casts",

package/dist/index.d.ts

@@ -53,6 +53,8 @@ export { CommandPalette } from "./components/CommandPalette/index.js";
 export type { Command } from "./components/CommandPalette/index.js";
 export { Tree } from "./components/Tree/index.js";
 export type { TreeNode } from "./components/Tree/index.js";
+export { FileList, formatSize } from "./components/FileList/index.js";
+export type { ExplorerEntry, FileListColumn } from "./components/FileList/index.js";
 export type { MenuItem, MenuAction, MenuSeparator } from "./data/table/types.js";
 export { ButtonGroup } from "./components/ButtonGroup/index.js";
 export type { ButtonGroupItem, ButtonGroupSelect } from "./components/ButtonGroup/index.js";
@@ -74,7 +76,7 @@ export { default as Disclosure2 } from "./components/Disclosure2.svelte";
 export { default as Accordion2 } from "./components/Accordion2.svelte";
 export { default as DatePicker2 } from "./components/DatePicker2.svelte";
 export { default as SideBarMenu } from "./components/SideBarMenu/SideBarMenu.svelte";
-export type { SideBarMenuItem, SideBarMenuBadge, SideBarMenuBadgeVariant, SideBarMenuApi, SideBarMenuMode, SideBarMenuActiveRule, } from "./components/SideBarMenu/SideBarMenu.svelte";
+export type { SideBarMenuItem, SideBarMenuDivider, SideBarMenuEntry, SideBarMenuBadge, SideBarMenuBadgeVariant, SideBarMenuApi, SideBarMenuMode, SideBarMenuActiveRule, } from "./components/SideBarMenu/SideBarMenu.svelte";
 export { Breadcrumbs } from "./components/Breadcrumbs/index.js";
 export type { BreadcrumbItem } from "./components/Breadcrumbs/index.js";
 export { default as TabStrip } from "./components/TabStrip/TabStrip.svelte";

package/dist/index.js

@@ -55,6 +55,7 @@ export { default as Menu } from "./components/Menu.svelte";
 export { ContextMenu } from "./components/ContextMenu/index.js";
 export { CommandPalette } from "./components/CommandPalette/index.js";
 export { Tree } from "./components/Tree/index.js";
+export { FileList, formatSize } from "./components/FileList/index.js";
 export { ButtonGroup } from "./components/ButtonGroup/index.js";
 export { default as Checkbox } from "./components/Checkbox.svelte";
 export { default as Toggle } from "./components/Toggle.svelte";

package/docs/components.md

@@ -868,6 +868,28 @@ Hierarchical, expandable tree view (ARIA `tree`).
   select, Home/End
 - **Accessibility**: `role="tree"`/`treeitem` with `aria-level`/`-expanded`/`-selected`/`-disabled`
 
+### FileList
+
+The **details pane of a file explorer** — `Name · Date modified · Type · Size`, folders first. Shaped
+like an OS explorer (columns collapse by the component's own width via container queries), not a generic
+`DataTable`. **Consumer-driven**: the parent owns the data + every action; the component owns selection,
+sort, the rename field, and the drop highlight.
+
+- **Location**: `src/lib/components/FileList/FileList.svelte` · subpath `@spaethtech/svelte-ui/file-list`
+- **Types**: `ExplorerEntry` (`{ key, name, kind: 'drive'|'folder'|'file', size?, modified?, flags? }`),
+  `FileListColumn`; helper `formatSize(n, locale?)`
+- **State props (bindable)**: `selected` (`Set<string>`), `editing` (key being renamed), `sortCol`,
+  `sortDir`
+- **Other props**: `entries`, `loading`, `error`, `emptyText` (default localized), `canDrop`, `variant`
+  (selection accent), `formatDate(iso)` (override; default `Intl.DateTimeFormat(locale)`), `class`
+- **Callbacks** (actions): `onopen(e)` *(required)*, `oncontextmenu(ev, entry|null)` (not prevented, so
+  a wrapping `ContextMenu` opens), `ondropfiles(files, into|null)`, `ondelete(entries)`, `onrename(e)`,
+  `oncommitname(e, name|null)`, `onup()`, `onsort(col, dir)`
+- **Interaction**: click / Ctrl+click / Shift+click select; double-click or Enter opens; F2 renames in
+  place; Delete / Backspace / Ctrl+A / arrows; drag desktop files onto the pane or a folder row
+- **i18n**: column headers, Type labels, empty/aria strings via `UiMessages`; date/number via `locale`
+- **Composition**: built on `Input` (rename) + `Badge` (flags); pairs with `ContextMenu` + `Tree`
+
 ### ScrollArea
 
 Scroll container with a themed thin scrollbar.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spaethtech/svelte-ui",
-  "version": "0.21.1-dev.130.6593aa4",
+  "version": "0.21.1-dev.132.b812036",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/spaethtech/svelte-ui.git"
@@ -253,6 +253,10 @@
       "types": "./dist/components/Tree/index.d.ts",
       "svelte": "./dist/components/Tree/index.js"
     },
+    "./file-list": {
+      "types": "./dist/components/FileList/index.d.ts",
+      "svelte": "./dist/components/FileList/index.js"
+    },
     "./button-group": {
       "types": "./dist/components/ButtonGroup/index.d.ts",
       "svelte": "./dist/components/ButtonGroup/index.js"