@viniaraujo68/plinth 0.6.0 → 0.8.0

package/README.md

@@ -300,14 +300,14 @@ never rethrows, so an `{:catch error}` branch that renders it is safe on the ser
 | `@viniaraujo68/plinth/virtual`     | `Virtualizer`, `VirtualList`, `WindowedData`, `WindowedVirtualizer`, `DataList`                              |
 | `@viniaraujo68/plinth/url-state`   | `createUrlState`, `urlStore`, `SyncedState`, `createParamsCodec` and `param`, the codec contracts            |
 
-The components entry point ships `AsyncButton`, `Combobox`, `Copyable`, `DateRangePicker`,
+The components entry point ships `AsyncButton`, `Avatar`, `Combobox`, `Copyable`, `DateRangePicker`,
 `Dialog`, `DragHandle`, `Dropdown`, `ErrorDisplay`, `ErrorPage`, `JsonInput`, `JsonView`, `Listbox`, `LoadingButton`, `Logo`,
 `Modal`, `MultiSelect`, `Paginator`, `RefreshButton`, `RequestErrorDisplay`, `SegmentedControl`, `Select`, `Skeleton`, `Tabs`,
 `VirtualJsonView`
 and `Tooltip`. Every one of them has a page in the showcase.
 It also exports the mark's outline as data — `PICK_PATH` and `PICK_CLIP_PATH` — for anything
-that wants the pick as a silhouette of its own. Not for avatars: the shell draws a profile picture as
-a disc, and an app's should be one too.
+that wants the pick as a silhouette of its own. Not for avatars: a profile picture is a disc, which
+is what `Avatar` draws.
 
 **`Tabs`** switches what one panel shows: a `tablist` with a roving tabindex, where the arrow keys,
 Home and End move the selection and the selection follows the focus. It scrolls sideways on a phone
@@ -322,6 +322,9 @@ date fields, the pair is `YYYY-MM-DD`, and an empty end leaves that side open, s
 "all time" are pairs too. Presets can follow the calendar instead of a duration — `thisMonth`,
 `lastMonth`, `lastMonths(n)` and `allTime` build the usual ones, and any `range(now)` function will
 do. Every preset re-anchors on a timer, and a picker handed a pair opens on the preset that names it.
+`caption` puts visible text before the presets, as on `SegmentedControl`, and `size` (`sm` or `md`)
+sizes the presets and the typed fields together, so the fields line up with the buttons.
+`fieldLabels` puts the field labels `"above"` their fields (the default) or `"beside"` them.
 
 `JsonInput` edits a JSON document as text: it reports through a bindable `invalid` whether the text
 parses, shows the parser's message after the first blur, can reindent on blur, and sets the

package/dist/components/Avatar.svelte

@@ -0,0 +1,81 @@
+<script lang="ts">
+  import type { ClassValue } from "svelte/elements";
+  import { initials } from "./initials.js";
+
+  interface Props {
+    /** Whose avatar this is. Drawn as initials when there is no photo; never shown in full. */
+    name: string;
+    /** The photo's URL. Without one, or when it fails to load, the initials stand in for it. */
+    src?: string | null;
+    /**
+     * The disc's diameter, as any CSS length. A prop and not a class because an unlayered
+     * component rule beats a Tailwind utility whatever the source order, so `size-10` from the
+     * outside could never win. The initials scale with it.
+     */
+    size?: string;
+    class?: ClassValue;
+  }
+
+  let { name, src, size = "2rem", class: className }: Props = $props();
+
+  // Remembering which URL failed, rather than a flag, is what lets a new photo be tried again:
+  // a changed `src` no longer matches the failed one, with no effect to reset anything.
+  let failedSrc = $state<string | null>(null);
+</script>
+
+<!--
+@component
+A person on a disc: their photo when there is one, the first letter of their first and last name
+when there is not, and the initials again when the photo fails to load.
+
+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.
+
+```svelte
+<Avatar name="Ada Lovelace" />
+<Avatar name="Ada Lovelace" src={photoUrl} size="6rem" />
+```
+-->
+
+<span class={["plinth-avatar", className]} style:--plinth-avatar-size={size} aria-hidden="true">
+  {#if src && src !== failedSrc}
+    <img {src} alt="" onerror={() => (failedSrc = src)} />
+  {:else}
+    <span class="plinth-avatar-initials">{initials(name)}</span>
+  {/if}
+</span>
+
+<style>
+  .plinth-avatar {
+    display: flex;
+    flex-shrink: 0;
+    align-items: center;
+    justify-content: center;
+    width: var(--plinth-avatar-size);
+    height: var(--plinth-avatar-size);
+    overflow: hidden;
+    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: calc(var(--plinth-avatar-size) * 0.375);
+    font-weight: 500;
+    line-height: 1;
+  }
+
+  img {
+    width: 100%;
+    height: 100%;
+    object-fit: cover;
+  }
+
+  /* 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. */
+  .plinth-avatar-initials {
+    text-box: trim-both cap alphabetic;
+  }
+</style>

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

@@ -0,0 +1,29 @@
+import type { ClassValue } from "svelte/elements";
+interface Props {
+    /** Whose avatar this is. Drawn as initials when there is no photo; never shown in full. */
+    name: string;
+    /** The photo's URL. Without one, or when it fails to load, the initials stand in for it. */
+    src?: string | null;
+    /**
+     * The disc's diameter, as any CSS length. A prop and not a class because an unlayered
+     * component rule beats a Tailwind utility whatever the source order, so `size-10` from the
+     * outside could never win. The initials scale with it.
+     */
+    size?: string;
+    class?: ClassValue;
+}
+/**
+ * A person on a disc: their photo when there is one, the first letter of their first and last name
+ * when there is not, and the initials again when the photo fails to load.
+ *
+ * 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.
+ *
+ * ```svelte
+ * <Avatar name="Ada Lovelace" />
+ * <Avatar name="Ada Lovelace" src={photoUrl} size="6rem" />
+ * ```
+ */
+declare const Avatar: import("svelte").Component<Props, {}, "">;
+type Avatar = ReturnType<typeof Avatar>;
+export default Avatar;

package/dist/components/DateRangePicker.svelte

@@ -63,6 +63,21 @@
     toLabel?: string;
     /** Shown, as an alert, while the typed pair is out of order. */
     invalidRangeLabel?: string;
+    /**
+     * Visible text before the presets — "Period:". Passed to the {@link SegmentedControl}, so it
+     * sits on the preset row; `label` stays the accessible name.
+     */
+    caption?: string;
+    /**
+     * Sizes the presets and the custom fields together, so the fields line up with the buttons.
+     * `sm` is for a toolbar or a card header, where the default height would dominate.
+     */
+    size?: "sm" | "md";
+    /**
+     * Where the custom fields' labels sit: `"above"` stacks each one over its field, `"beside"`
+     * puts it before the field on the same line, so the whole picker can stay one row.
+     */
+    fieldLabels?: "above" | "beside";
     onchange?: (value: DateRange) => void;
   }
 
@@ -78,6 +93,9 @@
     fromLabel = "From",
     toLabel = "To",
     invalidRangeLabel = "The start must not be after the end.",
+    caption,
+    size = "md",
+    fieldLabels = "above",
     onchange,
   }: Props = $props();
 
@@ -106,6 +124,9 @@
 
   const isCustom = $derived(selection === CUSTOM_PRESET_ID);
   const days = $derived(mode === "date");
+  const fieldWrapper = $derived(
+    fieldLabels === "beside" ? "flex items-center gap-2" : "flex flex-col gap-1",
+  );
 
   const options = $derived([
     ...presets.map(({ id, label }) => ({ id, label })),
@@ -251,18 +272,18 @@ buttons are labelled by the list itself, through `DateRangePreset.label`.
 ```
 -->
 
-<div class={["flex flex-wrap items-end gap-x-4 gap-y-3", cls]}>
+<div class={["flex flex-wrap items-end gap-x-4 gap-y-3", cls]} data-size={size}>
   <!-- A segmented control rather than a joined row: a calendar picker easily offers six windows,
        and a joined row cannot wrap onto a second line at phone width. -->
-  <SegmentedControl {options} value={selection} {label} onchange={pick} />
+  <SegmentedControl {options} value={selection} {label} {caption} {size} onchange={pick} />
 
   {#if isCustom}
     <div class="flex flex-wrap items-end gap-x-4 gap-y-3">
-      <div class="flex flex-col gap-1">
+      <div class={fieldWrapper}>
         <label class="label text-xs" for={fromId}>{fromLabel}</label>
         <input
           id={fromId}
-          class="input min-h-11"
+          class="plinth-range-field input"
           class:input-error={rangeError !== null}
           type={days ? "date" : "datetime-local"}
           value={customFrom}
@@ -276,11 +297,11 @@ buttons are labelled by the list itself, through `DateRangePreset.label`.
         />
       </div>
 
-      <div class="flex flex-col gap-1">
+      <div class={fieldWrapper}>
         <label class="label text-xs" for={toId}>{toLabel}</label>
         <input
           id={toId}
-          class="input min-h-11"
+          class="plinth-range-field input"
           class:input-error={rangeError !== null}
           type={days ? "date" : "datetime-local"}
           value={customTo}
@@ -300,3 +321,28 @@ buttons are labelled by the list itself, through `DateRangePreset.label`.
     <p id={errorId} class="basis-full text-sm text-error" role="alert">{rangeError}</p>
   {/if}
 </div>
+
+<style>
+  /* Chrome sizes a date field to its text alone, leaving no room for the padding and the picker
+     icon, which then covers the last digit. */
+  .plinth-range-field {
+    height: 2rem;
+    min-width: 9rem;
+    font-size: 0.78rem;
+  }
+
+  .plinth-range-field[type="datetime-local"] {
+    min-width: 12.5rem;
+  }
+
+  [data-size="sm"] .plinth-range-field {
+    height: 1.625rem;
+    font-size: 0.7rem;
+  }
+
+  @media (max-width: 35rem) {
+    [data-size="md"] .plinth-range-field {
+      height: 2.5rem;
+    }
+  }
+</style>

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

@@ -44,6 +44,21 @@ interface Props {
     toLabel?: string;
     /** Shown, as an alert, while the typed pair is out of order. */
     invalidRangeLabel?: string;
+    /**
+     * Visible text before the presets — "Period:". Passed to the {@link SegmentedControl}, so it
+     * sits on the preset row; `label` stays the accessible name.
+     */
+    caption?: string;
+    /**
+     * Sizes the presets and the custom fields together, so the fields line up with the buttons.
+     * `sm` is for a toolbar or a card header, where the default height would dominate.
+     */
+    size?: "sm" | "md";
+    /**
+     * Where the custom fields' labels sit: `"above"` stacks each one over its field, `"beside"`
+     * puts it before the field on the same line, so the whole picker can stay one row.
+     */
+    fieldLabels?: "above" | "beside";
     onchange?: (value: DateRange) => void;
 }
 /**

package/dist/components/index.d.ts

@@ -1,4 +1,5 @@
 export { default as AsyncButton } from "./AsyncButton.svelte";
+export { default as Avatar } from "./Avatar.svelte";
 export { default as Combobox } from "./Combobox.svelte";
 export { default as Copyable } from "./Copyable.svelte";
 export { default as DateRangePicker } from "./DateRangePicker.svelte";

package/dist/components/index.js

@@ -1,4 +1,5 @@
 export { default as AsyncButton } from "./AsyncButton.svelte";
+export { default as Avatar } from "./Avatar.svelte";
 export { default as Combobox } from "./Combobox.svelte";
 export { default as Copyable } from "./Copyable.svelte";
 export { default as DateRangePicker } from "./DateRangePicker.svelte";

package/dist/index.d.ts

@@ -5,6 +5,6 @@
  * no portable way to import its own manifest, and a consumer that only wants to log a version
  * should not have to bundle one. `version.spec.ts` fails when this drifts from the manifest.
  */
-export declare const LIBRARY_VERSION = "0.6.0";
+export declare const LIBRARY_VERSION = "0.8.0";
 export { AsyncAction, type AsyncActionStatus, type AsyncFn } from "./async-action.svelte.js";
 export { reportError, setErrorReporter, type ErrorReporter } from "./error.js";

package/dist/index.js

@@ -5,7 +5,7 @@
  * no portable way to import its own manifest, and a consumer that only wants to log a version
  * should not have to bundle one. `version.spec.ts` fails when this drifts from the manifest.
  */
-export const LIBRARY_VERSION = "0.6.0";
+export const LIBRARY_VERSION = "0.8.0";
 // The root entry carries only what is not tied to one area: the error channel an app installs
 // once, and the async state machine the components are built on. Everything visual is reached
 // through a subpath — `/theme`, `/attachments`, `/components`, `/toast` — so importing a button

package/dist/shell/AppShell.svelte

@@ -9,7 +9,7 @@
   import { tooltip } from "../attachments/tooltip.js";
   import { getRoutingContext, resolvePathname, type ResolvedRoute } from "../routing.svelte.js";
   import { getUserContext, type UserData } from "../user/context.js";
-  import UserAvatar from "./UserAvatar.svelte";
+  import Avatar from "../components/Avatar.svelte";
 
   interface Props {
     /** The routed page. The shell owns the scroll container around it. */
@@ -557,7 +557,7 @@ shell rather than to the window, and the content area reserves its height plus
 
 {#snippet userBlock(data: UserData)}
   <div class="user-card">
-    <UserAvatar name={data.name} />
+    <Avatar name={data.name} />
     <span class="user-identity collapsible">
       <span class="user-name">{data.name}</span>
       <span class="user-email">{data.email}</span>

package/dist/shell/TopBar.svelte

@@ -3,7 +3,7 @@
   import type { ClassValue } from "svelte/elements";
   import Dropdown from "../components/Dropdown.svelte";
   import { getUserContext } from "../user/context.js";
-  import UserAvatar from "./UserAvatar.svelte";
+  import Avatar from "../components/Avatar.svelte";
 
   interface Props {
     /** The app's mark and name, at the start of the bar. Usually a link home. */
@@ -84,7 +84,7 @@ app uses — `--plinth-top-bar-width` caps the bar's content to match it.
           title={signedIn.name}
           panelClass="plinth-top-bar-menu dropdown rounded-box bg-base-100 p-2 shadow-lg"
         >
-          <UserAvatar name={signedIn.name} />
+          <Avatar 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. -->

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@viniaraujo68/plinth",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "A personal Svelte 5 design system: theme, application shell, interface primitives, routing metadata, a fetch wrapper and locale-aware formatters.",
   "license": "MIT",
   "type": "module",

package/dist/shell/UserAvatar.svelte

@@ -1,50 +0,0 @@
-<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

@@ -1,14 +0,0 @@
-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;