@viniaraujo68/plinth 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,93 @@
+import { type Snippet } from "svelte";
+import type { ClassValue } from "svelte/elements";
+import { type ResolvedRoute } from "../routing.svelte.js";
+interface Props {
+    /** The routed page. The shell owns the scroll container around it. */
+    children: Snippet;
+    /**
+     * The sidebar header, and the bottom sheet's header on narrow screens. Receives the collapse
+     * state so a caller can swap a wordmark for a mark instead of letting it be clipped.
+     */
+    brand?: Snippet<[{
+        collapsed: boolean;
+    }]>;
+    /** Extra sidebar footer content, above the user block. A theme picker usually goes here. */
+    footer?: Snippet;
+    /**
+     * Renders one entry's icon. Without it the shell emits `<span class={meta.icon}>`, which is
+     * what an icon font or an Iconify/Tailwind class wants; supply it to render SVG components.
+     */
+    icon?: Snippet<[ResolvedRoute]>;
+    /** Extra classes for the shell root — sizing, mostly. */
+    class?: ClassValue;
+    /**
+     * How many items the bottom bar renders, the trailing "More" item counted among them. Entries
+     * that do not fit collapse into the sheet "More" opens — and so does everything the bar has no
+     * room for at all: the brand, the footer snippet and the user block. "More" therefore appears
+     * with nothing overflowing whenever any of those exist, and costs a nav slot only once the bar
+     * is genuinely full: three entries in five slots render three plus "More", five render four
+     * plus "More" and put the fifth in the sheet.
+     */
+    bottomBarSlots?: number;
+    /** Where the collapse state is remembered. `null` turns persistence off. */
+    storageKey?: string | null;
+    /** Whether the sidebar is collapsed to icons. Bindable, so a page can drive it too. */
+    collapsed?: boolean;
+    /** Accessible name of both navigations. A prop because the library ships no translations. */
+    navLabel?: string;
+    /** Accessible name of the collapse button. */
+    collapseLabel?: string;
+    /** Label of the bottom bar's overflow item, and heading of the sheet it opens. */
+    moreLabel?: string;
+    /** Accessible name of the sheet's close button. */
+    closeLabel?: string;
+    /** Label of the sign-out control, which only appears when the user context can sign out. */
+    logoutLabel?: string;
+}
+/**
+ * The application shell: a collapsible sidebar on wide viewports, a fixed bottom bar on narrow ones,
+ * both fed by the same `RoutingContext`. The route tree is declared once, by the filesystem and the
+ * routing config; nothing here re-states it.
+ *
+ * Which form shows is decided by a **container query on the shell root**, not by JavaScript. There is
+ * no resize listener and no `matchMedia`, so nothing flashes the wrong layout on the first paint —
+ * and because the root is its own container, the shell can be dropped into a narrow box to render its
+ * mobile form on a desktop, which is exactly what the showcase does.
+ *
+ * Entries come from `routing.children("/")`, minus plumbing (no `title`), minus any route with no page
+ * of its own to link to, and minus anything the user context gates out. Home, when declared, is derived off the trail and rendered as the sidebar's
+ * header entry and as the bottom bar's first item. It is current on the exact root and nowhere else —
+ * every route is below it — while every other entry is current for its whole subtree, so exactly one
+ * entry is ever marked, in either form.
+ *
+ * The bar form has no sidebar, and so no brand, no footer and no user block. All three move into the
+ * sheet behind the "More" item, which is therefore shown whenever there is anything to put there —
+ * overflowing entries, a `brand` snippet, a `footer` snippet or a signed-in user — and not only on an
+ * overflow. The sheet reads brand, then the entries that did not fit, then `footer`, then the user
+ * block with its sign-out control. Choosing an entry dismisses it; using a footer control does not.
+ *
+ * Icons: `meta.icon` is an uninterpreted string, so by default it is handed straight to markup as
+ * `<span class={meta.icon}>` — the shape an icon font or an Iconify/Tailwind class wants. Pass the
+ * `icon` snippet to render something else, an SVG component for instance, and `meta.icon` becomes
+ * whatever the app wants it to mean.
+ *
+ * The shell fills its parent, so give it one with a height (`<div class="h-dvh">`, or `html, body {
+ * height: 100% }`). It owns the page's scroll container — the bar is pinned to the bottom of the
+ * shell rather than to the window, and the content area reserves its height plus
+ * `env(safe-area-inset-bottom)` so nothing ends up underneath it.
+ *
+ * ```svelte
+ * <AppShell>
+ * {#snippet brand({ collapsed })}
+ *   <a href="/">{collapsed ? "A" : "Acme"}</a>
+ * {/snippet}
+ * {#snippet footer()}
+ *   <ThemeToggle />
+ * {/snippet}
+ * {@render page()}
+ * </AppShell>
+ * ```
+ */
+declare const AppShell: import("svelte").Component<Props, {}, "collapsed">;
+type AppShell = ReturnType<typeof AppShell>;
+export default AppShell;

package/dist/shell/Breadcrumbs.svelte

@@ -0,0 +1,78 @@
+<script lang="ts">
+  /* Same reason as in `AppShell`: the lint rule can only see a literal `resolve()`, and a runtime
+     pathname has no literal route to give it. */
+  /* eslint-disable svelte/no-navigation-without-resolve */
+  import { getRoutingContext, resolvePathname } from "../routing.svelte.js";
+  import type { Crumb } from "./crumbs.js";
+
+  interface Props {
+    /**
+     * A trail to render verbatim, root first. Nothing is filtered — the caller already chose what
+     * to show — so keep `routeId` unique across entries. Omit it and the trail comes from the
+     * routing context, which then has to be set.
+     */
+    crumbs?: Crumb[];
+    /** Accessible name of the landmark. A prop because the library ships no translations. */
+    label?: string;
+  }
+
+  const { crumbs: custom, label = "Breadcrumb" }: Props = $props();
+
+  // The context getter THROWS when nothing set one, so it is only reached for when the caller did
+  // not bring their own trail. That is what lets custom breadcrumbs work in an app with no routing
+  // context at all. Whether an instance is custom or context-driven is settled at init, on purpose:
+  // swapping a live component between the two modes is not a thing worth supporting.
+  // svelte-ignore state_referenced_locally
+  const routing = custom === undefined ? getRoutingContext() : null;
+
+  // Plumbing entries stay in `matched` so a role gate declared halfway up the tree remains
+  // reachable; they have no business being a crumb.
+  const trail = $derived(custom ?? routing!.matched.filter((r) => r.meta.title !== undefined));
+</script>
+
+<!--
+@component
+The page's breadcrumb trail, derived from the routing context: every titled entry on the current
+match, root first, each one a link except the last and except any section with no page behind it.
+
+Pass `crumbs` to render a trail of your own instead — same grammar, caller-owned content. An entry
+only needs `routeId` and `label`, so appending a leaf the route tree cannot know about is cheap:
+
+```svelte
+<Breadcrumbs crumbs={[...routing.matched, { routeId: "leaf", label: order.reference }]} />
+```
+-->
+
+<nav class="breadcrumbs py-1 text-sm" aria-label={label}>
+  <ul>
+    {#each trail as crumb, index (crumb.routeId)}
+      {@const isLast = index === trail.length - 1}
+      {@const isLink = !isLast && crumb.navigable === true && crumb.pathname !== undefined}
+      <li>
+        {#if isLink}
+          <a class="crumb gap-1.5 text-base-content/50" href={resolvePathname(crumb.pathname!)}>
+            {#if crumb.routeId === "/" && crumb.meta?.icon}
+              <span class="size-4 {crumb.meta.icon}" aria-hidden="true"></span>
+            {/if}
+            {crumb.label}
+          </a>
+        {:else}
+          <!-- The last crumb names the page the user is already on, which is what `aria-current`
+               is for; the intermediate non-links are headings and get neither. -->
+          <span
+            class={[
+              "crumb cursor-default gap-1.5 no-underline",
+              isLast ? "text-base-content" : "text-base-content/50",
+            ]}
+            aria-current={isLast ? "page" : undefined}
+          >
+            {#if crumb.routeId === "/" && crumb.meta?.icon}
+              <span class="size-4 {crumb.meta.icon}" aria-hidden="true"></span>
+            {/if}
+            {crumb.label}
+          </span>
+        {/if}
+      </li>
+    {/each}
+  </ul>
+</nav>

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

@@ -0,0 +1,25 @@
+import type { Crumb } from "./crumbs.js";
+interface Props {
+    /**
+     * A trail to render verbatim, root first. Nothing is filtered — the caller already chose what
+     * to show — so keep `routeId` unique across entries. Omit it and the trail comes from the
+     * routing context, which then has to be set.
+     */
+    crumbs?: Crumb[];
+    /** Accessible name of the landmark. A prop because the library ships no translations. */
+    label?: string;
+}
+/**
+ * The page's breadcrumb trail, derived from the routing context: every titled entry on the current
+ * match, root first, each one a link except the last and except any section with no page behind it.
+ *
+ * Pass `crumbs` to render a trail of your own instead — same grammar, caller-owned content. An entry
+ * only needs `routeId` and `label`, so appending a leaf the route tree cannot know about is cheap:
+ *
+ * ```svelte
+ * <Breadcrumbs crumbs={[...routing.matched, { routeId: "leaf", label: order.reference }]} />
+ * ```
+ */
+declare const Breadcrumbs: import("svelte").Component<Props, {}, "">;
+type Breadcrumbs = ReturnType<typeof Breadcrumbs>;
+export default Breadcrumbs;

package/dist/shell/crumbs.d.ts

@@ -0,0 +1,23 @@
+import type { RouteMeta } from "../routing.svelte.js";
+/**
+ * One step of a breadcrumb trail.
+ *
+ * Deliberately a subset of {@link ResolvedRoute} rather than that type itself, so a page can
+ * append a leaf the route tree knows nothing about — a record's name it just fetched — with two
+ * fields instead of five.
+ *
+ * It lives in its own module rather than inside `Breadcrumbs.svelte` because a type declared in a
+ * component's instance script cannot be re-exported from the package's entry point, and a consumer
+ * building a custom trail needs to name this.
+ */
+export interface Crumb {
+    /** Keys the entry; `"/"` additionally marks the root, the only crumb that shows an icon. */
+    routeId: string;
+    /** The visible text. */
+    label: string;
+    /** Where a navigable, non-final crumb links. */
+    pathname?: string;
+    /** Whether this crumb links at all. A section with no page of its own is a heading. */
+    navigable?: boolean;
+    meta?: Pick<RouteMeta, "icon">;
+}

package/dist/shell/crumbs.js

@@ -0,0 +1 @@
+export {};

package/dist/shell/index.d.ts

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

package/dist/shell/index.js

@@ -0,0 +1,6 @@
+// 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.
+// `@viniaraujo68/plinth/shell`.
+export { default as AppShell } from "./AppShell.svelte";
+export { default as Breadcrumbs } from "./Breadcrumbs.svelte";

package/dist/table/ColumnMenu.svelte

@@ -0,0 +1,249 @@
+<script lang="ts" generics="T">
+  import Dropdown from "../components/Dropdown.svelte";
+  import {
+    canHideColumn,
+    isColumnHideable,
+    isColumnStateEmpty,
+    isColumnVisible,
+    moveColumn,
+    orderColumns,
+    setColumnVisible,
+  } from "./columns.js";
+  import type { Column, ColumnState } from "./types.js";
+
+  interface Props {
+    columns: readonly Column<T>[];
+    layout: ColumnState | undefined;
+    onchange: (layout: ColumnState | undefined) => void;
+    /** The trigger's text, and the menu's accessible name. */
+    label: string;
+    resetLabel: string;
+    moveLabel: (column: Column<T>, direction: "up" | "down") => string;
+  }
+
+  let { columns, layout, onchange, label, resetLabel, moveLabel }: Props = $props();
+
+  const ordered = $derived(orderColumns(columns, layout));
+
+  let dragging = $state<string | null>(null);
+  let target = $state<{ key: string; after: boolean } | null>(null);
+
+  const move = (key: string, to: number) => onchange(moveColumn(columns, layout, key, to));
+
+  const toggle = (column: Column<T>, visible: boolean) =>
+    onchange(setColumnVisible(layout, column.key, visible));
+
+  const onDragStart = (event: DragEvent, key: string) => {
+    dragging = key;
+    // Firefox starts no drag at all without data on the transfer, whatever the data is.
+    event.dataTransfer?.setData("text/plain", key);
+    if (event.dataTransfer) event.dataTransfer.effectAllowed = "move";
+  };
+
+  const onDragOver = (event: DragEvent, key: string) => {
+    if (dragging === null) return;
+    event.preventDefault();
+    const row = event.currentTarget as HTMLElement;
+    const box = row.getBoundingClientRect();
+    target = { key, after: event.clientY > box.top + box.height / 2 };
+  };
+
+  const onDrop = (event: DragEvent) => {
+    event.preventDefault();
+    if (dragging !== null && target !== null && target.key !== dragging) {
+      const keys = ordered.map((column) => column.key);
+      const from = keys.indexOf(dragging);
+      let to = keys.indexOf(target.key) + (target.after ? 1 : 0);
+      // The dragged row leaves the list before it is put back, so every slot past it moves up one.
+      if (from < to) to -= 1;
+      move(dragging, to);
+    }
+    onDragEnd();
+  };
+
+  const onDragEnd = () => {
+    dragging = null;
+    target = null;
+  };
+</script>
+
+<!--
+@component
+Internal to `DataTable`: the menu that shows, hides and reorders its columns. It is a `Dropdown`,
+so Escape, a click outside and the trigger itself all close it without a listener of this file's
+own.
+
+Reordering is offered twice. Dragging a row is the quick way with a mouse, and it is native HTML
+drag and drop rather than pointer bookkeeping, so the browser draws the ghost and scrolls the list.
+The two arrow buttons on every row do the same one step at a time, and they are the only way to
+reorder from a keyboard or a screen reader — drag and drop has no keyboard story of its own.
+
+A column that is not hideable is listed without a checkbox, so the reader still sees it and can
+still move it; the last visible column's checkbox is disabled rather than hidden, for the same
+reason.
+-->
+
+<Dropdown
+  class="plinth-columns-trigger btn btn-ghost btn-sm"
+  panelClass="plinth-columns-panel rounded-box border border-base-content/10 bg-base-100 p-2 shadow-lg"
+  aria-label={label}
+>
+  {label}
+  <span class="plinth-columns-caret" aria-hidden="true">▾</span>
+  {#snippet content()}
+    <ul class="plinth-columns-list" aria-label={label}>
+      {#each ordered as column, index (column.key)}
+        {@const visible = isColumnVisible(column, layout)}
+        <li
+          class="plinth-columns-row"
+          class:plinth-dragging={dragging === column.key}
+          class:plinth-drop-before={target?.key === column.key && !target.after}
+          class:plinth-drop-after={target?.key === column.key && target.after}
+          draggable="true"
+          ondragstart={(event) => onDragStart(event, column.key)}
+          ondragover={(event) => onDragOver(event, column.key)}
+          ondrop={onDrop}
+          ondragend={onDragEnd}
+        >
+          <span class="plinth-columns-grip" aria-hidden="true">⠿</span>
+          {#if isColumnHideable(column)}
+            <label class="plinth-columns-label">
+              <input
+                type="checkbox"
+                class="checkbox checkbox-xs"
+                checked={visible}
+                disabled={visible && !canHideColumn(columns, layout, column.key)}
+                onchange={(event) => toggle(column, event.currentTarget.checked)}
+              />
+              {column.label}
+            </label>
+          {:else}
+            <span class="plinth-columns-label plinth-columns-locked">{column.label}</span>
+          {/if}
+          <button
+            type="button"
+            class="plinth-columns-move"
+            aria-label={moveLabel(column, "up")}
+            disabled={index === 0}
+            onclick={() => move(column.key, index - 1)}
+          >
+            ↑
+          </button>
+          <button
+            type="button"
+            class="plinth-columns-move"
+            aria-label={moveLabel(column, "down")}
+            disabled={index === ordered.length - 1}
+            onclick={() => move(column.key, index + 1)}
+          >
+            ↓
+          </button>
+        </li>
+      {/each}
+    </ul>
+    <button
+      type="button"
+      class="plinth-columns-reset btn btn-ghost btn-xs"
+      disabled={isColumnStateEmpty(layout)}
+      onclick={() => onchange(undefined)}
+    >
+      {resetLabel}
+    </button>
+  {/snippet}
+</Dropdown>
+
+<style>
+  .plinth-columns-caret {
+    font-size: 0.7em;
+    opacity: 0.6;
+  }
+
+  :global(.plinth-columns-panel) {
+    display: flex;
+    flex-direction: column;
+    gap: 0.25rem;
+    min-width: 14rem;
+    max-height: 22rem;
+    margin: 0.25rem 0 0;
+    overflow-y: auto;
+  }
+
+  .plinth-columns-list {
+    display: flex;
+    flex-direction: column;
+  }
+
+  .plinth-columns-row {
+    display: grid;
+    grid-template-columns: auto minmax(0, 1fr) auto auto;
+    align-items: center;
+    gap: 0.375rem;
+    padding: 0.25rem 0.375rem;
+    border-radius: var(--radius-field, 0.5rem);
+    /* Borders on both edges from the start, so showing the drop line does not shift the rows. */
+    border-top: 2px solid transparent;
+    border-bottom: 2px solid transparent;
+  }
+
+  .plinth-columns-row:hover {
+    background: color-mix(in oklch, var(--color-base-content) 5%, transparent);
+  }
+
+  .plinth-dragging {
+    opacity: 0.4;
+  }
+
+  .plinth-drop-before {
+    border-top-color: var(--color-primary);
+  }
+
+  .plinth-drop-after {
+    border-bottom-color: var(--color-primary);
+  }
+
+  .plinth-columns-grip {
+    cursor: grab;
+    color: color-mix(in oklch, var(--color-base-content) 40%, transparent);
+    user-select: none;
+  }
+
+  .plinth-columns-label {
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+    min-width: 0;
+    font-size: 0.875rem;
+    cursor: pointer;
+    overflow-wrap: anywhere;
+  }
+
+  .plinth-columns-locked {
+    padding-left: calc(1rem + 0.5rem);
+    cursor: default;
+    color: color-mix(in oklch, var(--color-base-content) 65%, transparent);
+  }
+
+  .plinth-columns-move {
+    display: grid;
+    place-items: center;
+    width: 1.5rem;
+    height: 1.5rem;
+    border-radius: var(--radius-field, 0.5rem);
+    color: color-mix(in oklch, var(--color-base-content) 60%, transparent);
+    cursor: pointer;
+  }
+
+  .plinth-columns-move:hover:not(:disabled) {
+    background: color-mix(in oklch, var(--color-base-content) 10%, transparent);
+    color: var(--color-base-content);
+  }
+
+  .plinth-columns-move:disabled {
+    opacity: 0.3;
+    cursor: default;
+  }
+
+  .plinth-columns-reset {
+    align-self: flex-end;
+  }
+</style>

package/dist/table/ColumnMenu.svelte.d.ts

@@ -0,0 +1,47 @@
+import type { Column, ColumnState } from "./types.js";
+declare function $$render<T>(): {
+    props: {
+        columns: readonly Column<T>[];
+        layout: ColumnState | undefined;
+        onchange: (layout: ColumnState | undefined) => void;
+        /** The trigger's text, and the menu's accessible name. */
+        label: string;
+        resetLabel: string;
+        moveLabel: (column: Column<T>, direction: "up" | "down") => string;
+    };
+    exports: {};
+    bindings: "";
+    slots: {};
+    events: {};
+};
+declare class __sveltets_Render<T> {
+    props(): ReturnType<typeof $$render<T>>['props'];
+    events(): ReturnType<typeof $$render<T>>['events'];
+    slots(): ReturnType<typeof $$render<T>>['slots'];
+    bindings(): "";
+    exports(): {};
+}
+interface $$IsomorphicComponent {
+    new <T>(options: import('svelte').ComponentConstructorOptions<ReturnType<__sveltets_Render<T>['props']>>): import('svelte').SvelteComponent<ReturnType<__sveltets_Render<T>['props']>, ReturnType<__sveltets_Render<T>['events']>, ReturnType<__sveltets_Render<T>['slots']>> & {
+        $$bindings?: ReturnType<__sveltets_Render<T>['bindings']>;
+    } & ReturnType<__sveltets_Render<T>['exports']>;
+    <T>(internal: unknown, props: ReturnType<__sveltets_Render<T>['props']> & {}): ReturnType<__sveltets_Render<T>['exports']>;
+    z_$$bindings?: ReturnType<__sveltets_Render<any>['bindings']>;
+}
+/**
+ * Internal to `DataTable`: the menu that shows, hides and reorders its columns. It is a `Dropdown`,
+ * so Escape, a click outside and the trigger itself all close it without a listener of this file's
+ * own.
+ *
+ * Reordering is offered twice. Dragging a row is the quick way with a mouse, and it is native HTML
+ * drag and drop rather than pointer bookkeeping, so the browser draws the ghost and scrolls the list.
+ * The two arrow buttons on every row do the same one step at a time, and they are the only way to
+ * reorder from a keyboard or a screen reader — drag and drop has no keyboard story of its own.
+ *
+ * A column that is not hideable is listed without a checkbox, so the reader still sees it and can
+ * still move it; the last visible column's checkbox is disabled rather than hidden, for the same
+ * reason.
+ */
+declare const ColumnMenu: $$IsomorphicComponent;
+type ColumnMenu<T> = InstanceType<typeof ColumnMenu<T>>;
+export default ColumnMenu;