@viniaraujo68/plinth 0.3.1 → 0.5.0

package/dist/shell/TopBar.svelte

@@ -0,0 +1,191 @@
+<script lang="ts">
+  import type { Snippet } from "svelte";
+  import type { ClassValue } from "svelte/elements";
+  import Dropdown from "../components/Dropdown.svelte";
+  import { getUserContext } from "../user/context.js";
+  import UserAvatar from "./UserAvatar.svelte";
+
+  interface Props {
+    /** The app's mark and name, at the start of the bar. Usually a link home. */
+    brand?: Snippet;
+    /**
+     * Controls at the end of the bar, before the account menu: a language toggle, a theme toggle,
+     * the sign-in and sign-up links a visitor who is not signed in needs.
+     */
+    actions?: Snippet;
+    /**
+     * The account menu's own entries, as `<li>` elements — "My groups", "Account". They sit between
+     * the user's name and the sign-out entry. Choosing one closes the menu.
+     */
+    menu?: Snippet;
+    /** Accessible name of the avatar that opens the menu. A prop because the library ships no translations. */
+    menuLabel?: string;
+    /** The menu's sign-out entry. Shown only when the user context has somewhere to sign out to. */
+    logoutLabel?: string;
+    class?: ClassValue;
+  }
+
+  let {
+    brand,
+    actions,
+    menu,
+    menuLabel = "Account",
+    logoutLabel = "Sign out",
+    class: className,
+  }: Props = $props();
+
+  const user = getUserContext();
+  const signedIn = $derived(user.status === "authenticated" ? user.data : null);
+
+  let accountMenu = $state<Dropdown>();
+
+  /**
+   * Closes the menu once something in it is chosen. The popover light-dismisses on a click outside
+   * it, never on one inside, and a link that navigates within the app leaves the bar — and the open
+   * panel — mounted. Delegated from the list, so the app's own entries need no handler of their own.
+   */
+  const closeOnChoice = (event: MouseEvent) => {
+    if ((event.target as Element | null)?.closest("a, button")) accountMenu?.close();
+  };
+
+  const signOut = async () => {
+    await user.logout?.();
+  };
+</script>
+
+<!--
+@component
+A bar across the top of the page, for an app with too little navigation to fill `AppShell`'s
+sidebar: the brand at the start, the app's controls at the end and, once someone is signed in, their
+avatar, which opens an account menu with their name, the app's entries and signing out.
+
+It reads the signed-in user from the user context, as `AppShell` does, so the same
+`setUserContext` drives both. It owns no page layout: put the page below it, at whatever width the
+app uses — `--plinth-top-bar-width` caps the bar's content to match it.
+
+```svelte
+<TopBar menuLabel="Account menu" logoutLabel="Sign out">
+  {#snippet brand()}<a href="/">Acme</a>{/snippet}
+  {#snippet actions()}<ThemeToggle iconOnly />{/snippet}
+  {#snippet menu()}<li><a href="/account">Account</a></li>{/snippet}
+</TopBar>
+```
+-->
+<header class={["plinth-top-bar", className]}>
+  <div class="plinth-top-bar-inner">
+    <div class="plinth-top-bar-brand">{@render brand?.()}</div>
+    <div class="plinth-top-bar-end">
+      {@render actions?.()}
+      {#if signedIn}
+        <Dropdown
+          bind:this={accountMenu}
+          class="plinth-top-bar-account"
+          aria-label={menuLabel}
+          title={signedIn.name}
+          panelClass="plinth-top-bar-menu dropdown rounded-box bg-base-100 p-2 shadow-lg"
+        >
+          <UserAvatar name={signedIn.name} />
+          {#snippet content()}
+            <!-- The handler only reacts to a click that landed on a link or a button inside, and a
+                 keyboard activates those with a click event of its own, so nothing is mouse-only. -->
+            <!-- svelte-ignore a11y_click_events_have_key_events, a11y_no_noninteractive_element_interactions -->
+            <ul class="menu w-full p-0" onclick={closeOnChoice}>
+              <li class="plinth-top-bar-identity menu-title">
+                <span class="plinth-top-bar-name">{signedIn.name}</span>
+                {#if signedIn.email}<span class="plinth-top-bar-email">{signedIn.email}</span>{/if}
+              </li>
+              {@render menu?.()}
+              {#if user.logout}
+                <li><button type="button" onclick={signOut}>{logoutLabel}</button></li>
+              {/if}
+            </ul>
+          {/snippet}
+        </Dropdown>
+      {/if}
+    </div>
+  </div>
+</header>
+
+<style>
+  .plinth-top-bar {
+    position: sticky;
+    top: 0;
+    z-index: 50;
+    border-bottom: 1px solid color-mix(in oklch, var(--color-base-content) 12%, transparent);
+    background-color: color-mix(in oklch, var(--color-base-100) 82%, transparent);
+    backdrop-filter: blur(12px);
+  }
+
+  .plinth-top-bar-inner {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 0.75rem;
+    max-width: var(--plinth-top-bar-width, none);
+    height: 4rem;
+    margin-inline: auto;
+    padding-inline: 1.25rem;
+  }
+
+  .plinth-top-bar-brand {
+    display: flex;
+    min-width: 0;
+    align-items: center;
+  }
+
+  .plinth-top-bar-end {
+    display: flex;
+    flex-shrink: 0;
+    align-items: center;
+    gap: 0.75rem;
+  }
+
+  @media (max-width: 35rem) {
+    .plinth-top-bar-inner {
+      padding-inline: 1rem;
+    }
+
+    .plinth-top-bar-end {
+      gap: 0.5rem;
+    }
+  }
+
+  /* The trigger and the panel are `Dropdown`'s elements, which this component's scoped rules do
+     not reach; their classes come in through props, hence the global selectors. */
+  :global(.plinth-top-bar-account) {
+    display: grid;
+    place-items: center;
+    padding: 0;
+    border: none;
+    border-radius: 9999px;
+    background: none;
+    cursor: pointer;
+  }
+
+  :global(.plinth-top-bar-account:focus-visible) {
+    outline: 2px solid var(--color-primary);
+    outline-offset: 2px;
+  }
+
+  :global(.plinth-top-bar-menu) {
+    width: 13rem;
+    border: 1px solid color-mix(in oklch, var(--color-base-content) 12%, transparent);
+  }
+
+  .plinth-top-bar-identity {
+    display: flex;
+    flex-direction: column;
+    gap: 0.125rem;
+  }
+
+  .plinth-top-bar-name,
+  .plinth-top-bar-email {
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  .plinth-top-bar-email {
+    font-weight: 400;
+  }
+</style>

package/dist/shell/TopBar.svelte.d.ts

@@ -0,0 +1,41 @@
+import type { Snippet } from "svelte";
+import type { ClassValue } from "svelte/elements";
+interface Props {
+    /** The app's mark and name, at the start of the bar. Usually a link home. */
+    brand?: Snippet;
+    /**
+     * Controls at the end of the bar, before the account menu: a language toggle, a theme toggle,
+     * the sign-in and sign-up links a visitor who is not signed in needs.
+     */
+    actions?: Snippet;
+    /**
+     * The account menu's own entries, as `<li>` elements — "My groups", "Account". They sit between
+     * the user's name and the sign-out entry. Choosing one closes the menu.
+     */
+    menu?: Snippet;
+    /** Accessible name of the avatar that opens the menu. A prop because the library ships no translations. */
+    menuLabel?: string;
+    /** The menu's sign-out entry. Shown only when the user context has somewhere to sign out to. */
+    logoutLabel?: string;
+    class?: ClassValue;
+}
+/**
+ * A bar across the top of the page, for an app with too little navigation to fill `AppShell`'s
+ * sidebar: the brand at the start, the app's controls at the end and, once someone is signed in, their
+ * avatar, which opens an account menu with their name, the app's entries and signing out.
+ *
+ * It reads the signed-in user from the user context, as `AppShell` does, so the same
+ * `setUserContext` drives both. It owns no page layout: put the page below it, at whatever width the
+ * app uses — `--plinth-top-bar-width` caps the bar's content to match it.
+ *
+ * ```svelte
+ * <TopBar menuLabel="Account menu" logoutLabel="Sign out">
+ * {#snippet brand()}<a href="/">Acme</a>{/snippet}
+ * {#snippet actions()}<ThemeToggle iconOnly />{/snippet}
+ * {#snippet menu()}<li><a href="/account">Account</a></li>{/snippet}
+ * </TopBar>
+ * ```
+ */
+declare const TopBar: import("svelte").Component<Props, {}, "">;
+type TopBar = ReturnType<typeof TopBar>;
+export default TopBar;

package/dist/shell/UserAvatar.svelte

@@ -0,0 +1,50 @@
+<script lang="ts">
+  import type { ClassValue } from "svelte/elements";
+  import { initials } from "./initials.js";
+
+  interface Props {
+    /** Whose avatar this is. Only the initials are drawn; the name itself is the caller's to show. */
+    name: string;
+    class?: ClassValue;
+  }
+
+  let { name, class: className }: Props = $props();
+</script>
+
+<!--
+@component
+A signed-in user's initials on a disc. Hidden from assistive technology: every place that draws it
+also shows the name next to it, or labels the control it sits in, and initials read aloud as
+letters would only repeat that.
+-->
+<span class={["avatar-initials", className]} aria-hidden="true"
+  ><span class="avatar-initials-text">{initials(name)}</span></span
+>
+
+<style>
+  .avatar-initials {
+    display: flex;
+    flex-shrink: 0;
+    align-items: center;
+    justify-content: center;
+    width: 2rem;
+    height: 2rem;
+    border-radius: 9999px;
+    /* Solid rather than a wash: on the tinted bars this sits on, a 15% disc all but disappears.
+       `--color-primary-content` is the pair the theme guarantees against it in both modes. */
+    background-color: var(--color-primary);
+    color: var(--color-primary-content);
+    font-size: 0.75rem;
+    font-weight: 500;
+    line-height: 1;
+  }
+
+  /* Centring the line box centres the font's ascent and descent, not the letters: capitals sit
+     above the baseline with nothing hanging below, so in a font like Segoe UI Variable they land a
+     pixel low on a 2rem disc. Trimmed to cap height and baseline, the box is the letters, and the
+     disc centres them whatever the font. The inner element is what gets trimmed, because the
+     property applies to block containers and the disc is a flex container. */
+  .avatar-initials-text {
+    text-box: trim-both cap alphabetic;
+  }
+</style>

package/dist/shell/UserAvatar.svelte.d.ts

@@ -0,0 +1,14 @@
+import type { ClassValue } from "svelte/elements";
+interface Props {
+    /** Whose avatar this is. Only the initials are drawn; the name itself is the caller's to show. */
+    name: string;
+    class?: ClassValue;
+}
+/**
+ * A signed-in user's initials on a disc. Hidden from assistive technology: every place that draws it
+ * also shows the name next to it, or labels the control it sits in, and initials read aloud as
+ * letters would only repeat that.
+ */
+declare const UserAvatar: import("svelte").Component<Props, {}, "">;
+type UserAvatar = ReturnType<typeof UserAvatar>;
+export default UserAvatar;

package/dist/shell/index.d.ts

@@ -1,3 +1,5 @@
 export { default as AppShell } from "./AppShell.svelte";
 export { default as Breadcrumbs } from "./Breadcrumbs.svelte";
+export { default as NavigationProgress } from "./NavigationProgress.svelte";
+export { default as TopBar } from "./TopBar.svelte";
 export type { Crumb } from "./crumbs.js";

package/dist/shell/index.js

@@ -1,6 +1,10 @@
-// The application chrome around a routed page. Everything here reads the routing context rather
-// than a tree of its own, so the navigation an app declares once in `routes.ts` is the navigation
-// that renders — on a sidebar, on a bottom bar and in a breadcrumb trail alike.
+// The application chrome around a routed page. `AppShell` and `Breadcrumbs` read the routing
+// context rather than a tree of their own, so the navigation an app declares once in `routes.ts`
+// is the navigation that renders — on a sidebar, on a bottom bar and in a breadcrumb trail alike.
+// `TopBar` is the lighter alternative for an app with little to navigate, and
+// `NavigationProgress` goes with either.
 // `@viniaraujo68/plinth/shell`.
 export { default as AppShell } from "./AppShell.svelte";
 export { default as Breadcrumbs } from "./Breadcrumbs.svelte";
+export { default as NavigationProgress } from "./NavigationProgress.svelte";
+export { default as TopBar } from "./TopBar.svelte";

package/dist/shell/initials.d.ts

@@ -0,0 +1,6 @@
+/**
+ * The letters an avatar shows for a name: the first letter of the first word and of the last one,
+ * upper-cased — "Ada Lovelace" is "AL", "ada" is "A". A blank name gives "?" rather than an empty
+ * disc, which would read as a rendering bug.
+ */
+export declare const initials: (name: string) => string;

package/dist/shell/initials.js

@@ -0,0 +1,13 @@
+/**
+ * The letters an avatar shows for a name: the first letter of the first word and of the last one,
+ * upper-cased — "Ada Lovelace" is "AL", "ada" is "A". A blank name gives "?" rather than an empty
+ * disc, which would read as a rendering bug.
+ */
+export const initials = (name) => {
+    const words = name.split(/\s+/).filter(Boolean);
+    if (words.length === 0)
+        return "?";
+    const first = words[0][0];
+    const last = words.length > 1 ? words[words.length - 1][0] : "";
+    return `${first}${last}`.toUpperCase();
+};

package/dist/table/DataTable.svelte

@@ -1,7 +1,11 @@
 <script lang="ts" generics="T">
   import type { Snippet } from "svelte";
   import type { ClassValue } from "svelte/elements";
+  import Paginator, { type PaginatorLabels } from "../components/Paginator.svelte";
   import ColumnMenu from "./ColumnMenu.svelte";
+  import Skeleton from "../components/Skeleton.svelte";
+  import FilterBar from "./FilterBar.svelte";
+  import type { FilterLabels } from "./filter-labels.js";
   import {
     columnWidth,
     isColumnResizable,
@@ -11,8 +15,9 @@
     visibleColumns,
     writeColumnState,
   } from "./columns.js";
+  import { emptyFilter, filterableColumns, filterRows } from "./filter.js";
   import { ariaSort, cellText, nextSort, sortRows } from "./sort.js";
-  import type { Column, ColumnState, SortState } from "./types.js";
+  import type { Column, ColumnState, FilterGroup, SortState } from "./types.js";
 
   interface Props {
     rows: readonly T[];
@@ -92,6 +97,22 @@
     moveColumnLabel?: (column: Column<T>, direction: "up" | "down") => string;
     /** Names a column's resize handle for a screen reader. */
     resizeLabel?: (column: Column<T>) => string;
+    filters?: FilterGroup;
+    filterBar?: boolean;
+    filterGroups?: boolean;
+    filterLabels?: Partial<FilterLabels>;
+    loading?: boolean;
+    loadingRows?: number;
+    loadingLabel?: string;
+    error?: unknown;
+    errorState?: Snippet<[unknown, (() => void) | undefined]>;
+    errorLabel?: string;
+    retryLabel?: string;
+    onRetry?: () => void;
+    pageSize?: number;
+    page?: number;
+    pageSizes?: number[];
+    paginatorLabels?: Partial<PaginatorLabels>;
   }
 
   let {
@@ -114,17 +135,61 @@
     resetColumnsLabel = "Reset columns",
     moveColumnLabel = (column, direction) => `Move ${column.label} ${direction}`,
     resizeLabel = (column) => `Resize ${column.label}`,
+    filters = $bindable(emptyFilter()),
+    filterBar = true,
+    filterGroups = true,
+    loading = false,
+    loadingRows = 5,
+    loadingLabel = "Loading…",
+    error,
+    errorState,
+    errorLabel = "The rows could not be loaded.",
+    retryLabel = "Try again",
+    onRetry,
+    filterLabels,
+    pageSize = $bindable(),
+    page = $bindable(1),
+    pageSizes,
+    paginatorLabels,
   }: Props = $props();
 
+  const filtered = $derived(filterRows(rows, columns, filters));
+
   const sorted = $derived.by(() => {
     const column = columns.find((candidate) => candidate.key === sort?.key);
-    if (!sort || !column) return rows;
-    return sortRows(rows, column, sort.direction, locale);
+    if (!sort || !column) return filtered;
+    return sortRows(filtered, column, sort.direction, locale);
   });
 
+  const totalPages = $derived(
+    pageSize === undefined ? 1 : Math.max(1, Math.ceil(sorted.length / pageSize)),
+  );
+  const currentPage = $derived(Math.min(Math.max(1, Math.floor(page)), totalPages));
+  const offset = $derived(pageSize === undefined ? 0 : (currentPage - 1) * pageSize);
+  const visible = $derived(
+    pageSize === undefined ? sorted : sorted.slice(offset, offset + pageSize),
+  );
+
+  const showFilterBar = $derived(filterBar && filterableColumns(columns).length > 0);
+
+  const failed = $derived(error !== undefined && error !== null && error !== false);
+  const placeholders = $derived(
+    loading && !failed && visible.length === 0 ? Math.max(1, loadingRows) : 0,
+  );
+
+  const onFiltersChange = (next: FilterGroup) => {
+    filters = next;
+    page = 1;
+  };
+
+  const onPageSizeChange = (size: number) => {
+    pageSize = size;
+    page = 1;
+  };
+
   const shown = $derived(visibleColumns(columns, columnState));
   const sized = $derived(shown.some((column) => columnWidth(column, columnState) !== undefined));
-  const hasBar = $derived(toolbar !== undefined || columnsLabel !== undefined);
+  const hasBar = $derived(toolbar !== undefined || columnsLabel !== undefined || showFilterBar);
 
   let restored = $state(false);
 
@@ -246,8 +311,13 @@ part — `hideable`, `hiddenByDefault`, `resizable`, `minWidth`. The arrangement
 release neither loses a stored layout nor ends up somewhere nobody put it. Sorting by a column the
 reader hid keeps working: the order is about the rows, not about what is on screen.
 
-It stays short of a data grid — no filtering, no virtualization, no saved views. A table that
-needs those needs a different component.
+Columns that declare a `filter` get a chip bar in the table's bar, bound through `filters`; the
+rules are applied before the sort, and the same rules drive `filterRows` for a caller that filters
+outside the table. `pageSize` pages the filtered, sorted rows with a `Paginator` under the table,
+and the position handed to `cell` and `card` stays the row's place in the whole order.
+
+It stays short of a data grid — no virtualization, no saved views. A table that needs those needs a
+different component.
 
 ```svelte
 <DataTable
@@ -290,6 +360,16 @@ needs those needs a different component.
     {#if toolbar}
       <div class="plinth-table-toolbar">{@render toolbar()}</div>
     {/if}
+    {#if showFilterBar}
+      <FilterBar
+        class="plinth-table-filters"
+        {columns}
+        filter={filters}
+        onchange={onFiltersChange}
+        groups={filterGroups}
+        labels={filterLabels}
+      />
+    {/if}
     {#if columnsLabel !== undefined}
       <div class="plinth-table-columns">
         <ColumnMenu
@@ -305,12 +385,16 @@ needs those needs a different component.
   </div>
 {/if}
 
-<div class="plinth-table-wrap">
+<div class="plinth-table-wrap" class:plinth-refreshing={loading && !failed && visible.length > 0}>
+  {#if loading && !failed}
+    <div class="plinth-table-progress" role="progressbar" aria-label={loadingLabel}></div>
+  {/if}
   <table
     class={["plinth-table table", className]}
     class:has-card={card !== undefined}
     class:plinth-sized={sized}
     aria-label={label}
+    aria-busy={loading}
   >
     <thead>
       <tr>
@@ -354,14 +438,40 @@ needs those needs a different component.
     </thead>
 
     <tbody>
-      {#if sorted.length === 0}
+      {#if failed}
+        <tr>
+          <td class="plinth-failed" colspan={shown.length}>
+            {#if errorState}
+              {@render errorState(error, onRetry)}
+            {:else}
+              <div class="plinth-failed-body" role="alert">
+                <span>{errorLabel}</span>
+                {#if onRetry}
+                  <button type="button" class="btn btn-sm" onclick={onRetry}>{retryLabel}</button>
+                {/if}
+              </div>
+            {/if}
+          </td>
+        </tr>
+      {:else if placeholders > 0}
+        {#each { length: placeholders }, slot (slot)}
+          <tr class="plinth-placeholder" aria-hidden="true">
+            {#each shown as column (column.key)}
+              <td data-align={alignOf(column)} class="plinth-cell">
+                <Skeleton class="plinth-placeholder-bar" />
+              </td>
+            {/each}
+          </tr>
+        {/each}
+      {:else if visible.length === 0}
         <tr>
           <td class="plinth-empty" colspan={shown.length}>
             {#if empty}{@render empty()}{:else}No data{/if}
           </td>
         </tr>
       {:else}
-        {#each sorted as row, index (rowKey(row))}
+        {#each visible as row, position (rowKey(row))}
+          {@const index = offset + position}
           <!-- A row is not an interactive element, and dressing it as one would cost the grid
                semantics that make the table navigable in the first place. When a click handler is
                given the row takes focus and answers Enter and Space, which is the reachable part
@@ -400,8 +510,23 @@ needs those needs a different component.
   </table>
 </div>
 
+{#if pageSize !== undefined && sorted.length > 0 && !failed}
+  <Paginator
+    class="plinth-table-paginator"
+    pageNumber={currentPage}
+    {pageSize}
+    {pageSizes}
+    {totalPages}
+    totalItems={sorted.length}
+    onPageChange={(next) => (page = next)}
+    {onPageSizeChange}
+    labels={paginatorLabels}
+  />
+{/if}
+
 <style>
   .plinth-table-wrap {
+    position: relative;
     /* The whole breakpoint. Querying the container rather than the viewport is also what lets the
        table be dropped into a narrow box and render its card form on a desktop, which is how the
        showcase demonstrates both at once and how a test reaches either. */
@@ -427,6 +552,16 @@ needs those needs a different component.
     margin-left: auto;
   }
 
+  :global(.plinth-table-filters) {
+    flex: 1 1 16rem;
+  }
+
+  :global(.plinth-table-paginator) {
+    margin-top: 0.75rem;
+    color: color-mix(in oklch, var(--color-base-content) 70%, transparent);
+    font-size: 0.8125rem;
+  }
+
   /* A table with a dragged column is as wide as its columns add up to, rather than as wide as its
      box: stretched to the box, the browser would share the spare width out between the columns —
      the dragged one included — and a drag would never land where the pointer let go. */
@@ -519,6 +654,61 @@ needs those needs a different component.
     cursor: pointer;
   }
 
+  .plinth-table-progress {
+    position: absolute;
+    inset: 0 0 auto;
+    z-index: 1;
+    height: 2px;
+    overflow: hidden;
+    background: color-mix(in oklch, var(--color-primary) 15%, transparent);
+  }
+
+  .plinth-table-progress::after {
+    content: "";
+    position: absolute;
+    inset: 0 auto 0 0;
+    width: 35%;
+    background: var(--color-primary);
+    animation: plinth-table-progress 1.1s ease-in-out infinite;
+  }
+
+  @keyframes plinth-table-progress {
+    from {
+      transform: translateX(-100%);
+    }
+    to {
+      transform: translateX(300%);
+    }
+  }
+
+  .plinth-refreshing tbody {
+    opacity: 0.55;
+    transition: opacity 150ms;
+  }
+
+  :global(.plinth-placeholder-bar) {
+    display: inline-block;
+    width: 70%;
+    height: 0.85rem;
+  }
+
+  .plinth-placeholder td[data-align="right"] :global(.plinth-placeholder-bar) {
+    width: 45%;
+  }
+
+  .plinth-failed {
+    padding: 2rem 1rem;
+  }
+
+  .plinth-failed-body {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    gap: 0.75rem;
+    color: color-mix(in oklch, var(--color-base-content) 70%, transparent);
+    text-align: center;
+  }
+
   .plinth-empty {
     padding: 2rem 1rem;
     color: color-mix(in oklch, var(--color-base-content) 60%, transparent);