@ptbdynamic/plinth 0.0.0-stage → 0.2.0

package/packages/css/dist/header.css

@@ -0,0 +1,110 @@
+/*
+ * Header: the top bar of the phone shell, with a leading action, the page's title and trailing
+ * actions. It sticks to the top of the page as the content scrolls under it.
+ *
+ * <header class="plinth-header">
+ *   <div class="plinth-header-leading">
+ *     <a class="plinth-button plinth-icon-button" href="/inbox" data-variant="ghost"
+ *       data-size="md" aria-label="Back">
+ *       <span class="plinth-icon" data-size="md" data-mirror aria-hidden="true"><svg>…</svg></span>
+ *     </a>
+ *   </div>
+ *   <h1 class="plinth-header-title">Inbox</h1>
+ *   <div class="plinth-header-actions">
+ *     <button type="button" class="plinth-button plinth-icon-button" data-variant="ghost"
+ *       data-size="md" aria-label="Search">…</button>
+ *   </div>
+ * </header>
+ *
+ * The root is a <header>: at the top of the page (not inside <main>, <article> or <section>) it is
+ * the page's banner landmark, so a page has one. The title is an <h1>, the page's heading, and is
+ * required. It stays on one line and ends in an ellipsis when it doesn't fit.
+ *
+ * The leading part holds one action, usually an icon button: back (a link, with data-mirror on
+ * its icon so it points the other way in right-to-left text) or a menu button that opens a sheet
+ * (commandfor and command="show-modal"). The actions part holds the trailing actions, at most two
+ * or three icon buttons; put the rest in a menu. Both are optional, and printed only when they
+ * have content. Every icon button needs its own name (label). The header needs button.css and
+ * icon.css for them.
+ *
+ * Its height is the header.height component token (56px), plus env(safe-area-inset-top), which
+ * pads it below the status bar and the notch on a phone that draws under them (viewport-fit=cover);
+ * the inline padding clears the notch on a phone held sideways. It is sticky on the
+ * layer.sticky z-index, so it sits above the page and below sheets and menus (the top layer).
+ * Content scrolls under it, so the app sets scroll-padding-block-start on its scrolling element
+ * (calc(var(--plinth-header-height) + env(safe-area-inset-top))) to keep a focused element or an
+ * anchor's target from landing under the header.
+ *
+ * The actions sit var(--plinth-space-2) apart, so on a touch screen the 40px hit areas of 32px
+ * icon buttons don't overlap.
+ *
+ * The app owns the state: the header has no variants or states of its own. What the actions do is
+ * the app's (a link, a commandfor, wire:click, @click on the icon button).
+ */
+
+@layer plinth {
+  .plinth-header {
+    position: sticky;
+    inset-block-start: 0;
+    z-index: var(--plinth-layer-sticky);
+    box-sizing: border-box;
+    display: flex;
+    gap: var(--plinth-space-2);
+    align-items: center;
+    min-block-size: calc(var(--plinth-header-height) + env(safe-area-inset-top));
+    padding-block-start: env(safe-area-inset-top);
+    padding-inline: max(var(--plinth-space-2), env(safe-area-inset-left))
+      max(var(--plinth-space-2), env(safe-area-inset-right));
+    font-family: var(--plinth-font-family-body);
+    color: var(--plinth-color-text);
+    background-color: var(--plinth-color-surface);
+    border-block-end: var(--plinth-border-width-thin) solid var(--plinth-color-divider);
+  }
+
+  .plinth-header:dir(rtl) {
+    padding-inline: max(var(--plinth-space-2), env(safe-area-inset-right))
+      max(var(--plinth-space-2), env(safe-area-inset-left));
+  }
+
+  .plinth-header-leading,
+  .plinth-header-actions {
+    display: flex;
+    flex: none;
+    gap: var(--plinth-space-2);
+    align-items: center;
+  }
+
+  .plinth-header-title {
+    flex: 1 1 auto;
+    min-inline-size: 0;
+    margin: 0;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    font-size: var(--plinth-font-size-lg);
+    font-weight: var(--plinth-font-weight-semibold);
+    line-height: var(--plinth-font-leading-tight);
+    letter-spacing: var(--plinth-font-tracking-tight);
+    white-space: nowrap;
+  }
+
+  /* Without a leading action or trailing actions, the title keeps the text's distance from the edge. */
+  .plinth-header-title:first-child {
+    margin-inline-start: var(--plinth-space-2);
+  }
+
+  .plinth-header-title:last-child {
+    margin-inline-end: var(--plinth-space-2);
+  }
+
+  @media (min-width: 768px) {
+    .plinth-header {
+      padding-inline: max(var(--plinth-space-4), env(safe-area-inset-left))
+        max(var(--plinth-space-4), env(safe-area-inset-right));
+    }
+
+    .plinth-header:dir(rtl) {
+      padding-inline: max(var(--plinth-space-4), env(safe-area-inset-right))
+        max(var(--plinth-space-4), env(safe-area-inset-left));
+    }
+  }
+}

package/packages/css/dist/icon.css

@@ -0,0 +1,51 @@
+/*
+ * Icon: a project's own SVG, sized by Plinth.
+ *
+ * Decorative (the default), hidden from assistive technology:
+ * <span class="plinth-icon" data-size="md" aria-hidden="true">
+ *   <svg viewBox="0 0 24 24">…</svg>
+ * </span>
+ *
+ * Meaningful, with a label (an img role makes the SVG inside presentational). Blade, Vue and
+ * React take it as `label`, or as an `aria-label` attribute; a blank label leaves the icon
+ * decorative:
+ * <span class="plinth-icon" data-size="md" role="img" aria-label="Warning">
+ *   <svg viewBox="0 0 24 24">…</svg>
+ * </span>
+ *
+ * Sizes (data-size): sm 16px, md 20px (default, also when the attribute is missing or unknown),
+ * lg 24px. data-mirror flips the icon in right-to-left text, for icons that point a direction.
+ *
+ * The SVG comes from the project, inline or as <use href="sprite.svg#name">. It should draw with
+ * currentColor; Plinth sets no fill or stroke, so outline and filled icon sets both keep theirs.
+ * The icon takes its colour from the text around it.
+ */
+
+@layer plinth {
+  .plinth-icon {
+    --plinth-icon-current-size: var(--plinth-size-icon-md);
+
+    display: inline-flex;
+    flex: none;
+    inline-size: var(--plinth-icon-current-size);
+    block-size: var(--plinth-icon-current-size);
+    vertical-align: middle;
+  }
+
+  .plinth-icon[data-size='sm'] {
+    --plinth-icon-current-size: var(--plinth-size-icon-sm);
+  }
+
+  .plinth-icon[data-size='lg'] {
+    --plinth-icon-current-size: var(--plinth-size-icon-lg);
+  }
+
+  .plinth-icon > svg {
+    inline-size: 100%;
+    block-size: 100%;
+  }
+
+  .plinth-icon[data-mirror]:dir(rtl) > svg {
+    transform: scaleX(-1);
+  }
+}

package/packages/css/dist/list-card.css

@@ -0,0 +1,76 @@
+/*
+ * List card: a group of list rows on a raised surface, with an optional heading and footer note.
+ *
+ * <div class="plinth-list-card">
+ *   <h2 class="plinth-list-card-heading">Account</h2>
+ *   <ul class="plinth-list-card-list" role="list">
+ *     <li><a class="plinth-list-row" href="…">…</a></li>
+ *     <li><div class="plinth-list-row">…</div></li>
+ *   </ul>
+ *   <p class="plinth-list-card-footer">Changes apply to every device.</p>
+ * </div>
+ *
+ * The heading and the footer are optional, and sit outside the raised surface: the heading above
+ * it, the footer note below. The heading is an <h2> by default; pick the level that fits the page
+ * (heading-level h2 to h6 in Blade, headingLevel in Vue).
+ *
+ * The list is the raised surface (color.surface-raised, radius.container, a hairline in
+ * color.border; no shadow, per ADR 3: the card does not float). The card resets the list's
+ * margin, padding and bullets, and prints role="list" so Safari keeps announcing it. Each row
+ * goes in its own <li> and keeps its own root, states and divider; the surface clips the rows'
+ * hover and selection tints to its corners, and anything a row positions outside itself (a
+ * popover or a dialog is in the top layer, so it is not). The first and last rows take the
+ * surface's inner radius, so their focus ring, drawn inside the row, follows the corners.
+ */
+
+@layer plinth {
+  .plinth-list-card {
+    display: flex;
+    flex-direction: column;
+    gap: var(--plinth-space-2);
+    min-inline-size: 0;
+    font-family: var(--plinth-font-family-body);
+    color: var(--plinth-color-text);
+  }
+
+  .plinth-list-card-heading {
+    padding-inline: var(--plinth-space-4);
+    margin: 0;
+    font-size: var(--plinth-font-size-sm);
+    font-weight: var(--plinth-font-weight-medium);
+    line-height: var(--plinth-font-leading-normal);
+    color: var(--plinth-color-text-muted);
+    overflow-wrap: anywhere;
+  }
+
+  .plinth-list-card-list {
+    padding: 0;
+    margin: 0;
+    overflow: hidden;
+    list-style: none;
+    background-color: var(--plinth-color-surface-raised);
+    border: var(--plinth-border-width-thin) solid var(--plinth-color-border);
+    border-radius: var(--plinth-radius-container);
+  }
+
+  .plinth-list-card-footer {
+    padding-inline: var(--plinth-space-4);
+    margin: 0;
+    font-size: var(--plinth-font-size-sm);
+    line-height: var(--plinth-font-leading-normal);
+    color: var(--plinth-color-text-muted);
+    overflow-wrap: anywhere;
+  }
+
+  .plinth-list-card-list > li:first-child > .plinth-list-row {
+    border-start-start-radius: calc(
+      var(--plinth-radius-container) - var(--plinth-border-width-thin)
+    );
+    border-start-end-radius: calc(var(--plinth-radius-container) - var(--plinth-border-width-thin));
+  }
+
+  .plinth-list-card-list > li:last-child > .plinth-list-row {
+    border-end-start-radius: calc(var(--plinth-radius-container) - var(--plinth-border-width-thin));
+    border-end-end-radius: calc(var(--plinth-radius-container) - var(--plinth-border-width-thin));
+  }
+}

package/packages/css/dist/list-row.css

@@ -0,0 +1,164 @@
+/*
+ * List row: one row of a list or a sheet, 44px tall at least.
+ *
+ * <div class="plinth-list-row">
+ *   <span class="plinth-list-row-leading">an icon or an avatar</span>
+ *   <span class="plinth-list-row-content">
+ *     <span class="plinth-list-row-title">Notifications</span>
+ *     <span class="plinth-list-row-description">Email and push</span>
+ *   </span>
+ *   <span class="plinth-list-row-trailing">
+ *     a value, a badge or a control
+ *     <span class="plinth-icon plinth-list-row-chevron" data-size="sm" data-mirror
+ *       aria-hidden="true"><svg>…</svg></span>
+ *   </span>
+ * </div>
+ *
+ * The leading slot, the description and the trailing slot are optional; the chevron is the
+ * row's own (chevron in Blade and Vue), and points the other way in right-to-left text.
+ *
+ * The root is the element the app talks to (ADR 2):
+ * - a static row is a <div>;
+ * - a row that navigates is <a class="plinth-list-row" href="…">;
+ * - a row that acts is <button type="button" class="plinth-list-row">.
+ * A link or button row holds no other control: a switch or an icon button in the trailing slot
+ * needs a static row, and its own accessible name.
+ *
+ * States:
+ * - current: aria-current="page" on a link row (or a static row) for the page being shown, set
+ *   by the app; the selection tint (accent-subtle, accent-text) and a heavier title. A button
+ *   row never prints it: a button is not a page.
+ * - disabled: `disabled` on a <button>; on a link, no href, role="link" and aria-disabled="true".
+ * - hover only where the device can hover; the focus ring on :focus-visible, drawn inside the
+ *   row (focus-ring.offset-inset).
+ *
+ * A hairline divider (color.divider) sits between two rows that follow each other, as siblings
+ * or each as the direct child of its own <li>; a wrapper element in between drops it. The app
+ * resets the list (margin, padding, list-style) and adds role="list", which Safari needs to keep
+ * announcing a list without bullets. The height is --plinth-list-row-height (44px); a description makes the
+ * row taller. Long titles and descriptions wrap; the trailing slot keeps its width up to half the
+ * row, and only a value longer than that wraps.
+ */
+
+@layer plinth {
+  .plinth-list-row {
+    box-sizing: border-box;
+    display: flex;
+    gap: var(--plinth-space-3);
+    align-items: center;
+    inline-size: 100%;
+    min-block-size: var(--plinth-list-row-height);
+    padding-block: var(--plinth-space-2);
+    padding-inline: var(--plinth-space-4);
+    margin: 0;
+    font-family: var(--plinth-font-family-body);
+    font-size: var(--plinth-font-size-md);
+    font-weight: var(--plinth-font-weight-regular);
+    line-height: var(--plinth-font-leading-tight);
+    color: var(--plinth-color-text);
+    text-align: start;
+    text-decoration: none;
+    background-color: transparent;
+    border: 0;
+    transition: background-color var(--plinth-duration-fast) var(--plinth-easing-standard);
+  }
+
+  :is(a, button).plinth-list-row {
+    cursor: pointer;
+  }
+
+  li + li > .plinth-list-row {
+    border-block-start: var(--plinth-border-width-thin) solid var(--plinth-color-divider);
+  }
+
+  .plinth-list-row + .plinth-list-row {
+    border-block-start: var(--plinth-border-width-thin) solid var(--plinth-color-divider);
+  }
+
+  @media (hover: hover) {
+    a.plinth-list-row[href]:not([aria-current='page']):hover,
+    button.plinth-list-row:enabled:not([aria-current='page']):hover {
+      background-color: var(--plinth-color-surface-hover);
+    }
+  }
+
+  a.plinth-list-row[href]:not([aria-current='page']):active,
+  button.plinth-list-row:enabled:not([aria-current='page']):active {
+    background-color: var(--plinth-color-surface-sunken);
+  }
+
+  .plinth-list-row[aria-current='page'] {
+    color: var(--plinth-color-accent-text);
+    background-color: var(--plinth-color-accent-subtle);
+  }
+
+  .plinth-list-row:disabled,
+  .plinth-list-row[aria-disabled='true'] {
+    cursor: not-allowed;
+    opacity: var(--plinth-opacity-disabled);
+  }
+
+  /* Inside the row, so a scrolling sheet or a card doesn't cut the ring off at the sides. */
+  .plinth-list-row:focus-visible {
+    outline: var(--plinth-focus-ring-width) solid var(--plinth-color-focus-ring);
+    outline-offset: var(--plinth-focus-ring-offset-inset);
+  }
+
+  .plinth-list-row-leading {
+    display: inline-flex;
+    flex: none;
+    align-items: center;
+    color: var(--plinth-color-text-muted);
+  }
+
+  .plinth-list-row-content {
+    display: flex;
+    flex: 1 1 auto;
+    flex-direction: column;
+    gap: var(--plinth-space-0-5);
+    min-inline-size: 0;
+  }
+
+  .plinth-list-row-title {
+    overflow-wrap: anywhere;
+  }
+
+  .plinth-list-row-description {
+    font-size: var(--plinth-font-size-sm);
+    line-height: var(--plinth-font-leading-normal);
+    color: var(--plinth-color-text-muted);
+    overflow-wrap: anywhere;
+  }
+
+  /* Keeps its width up to half the row, so a long title wraps before a short value does. */
+  .plinth-list-row-trailing {
+    display: inline-flex;
+    flex: none;
+    gap: var(--plinth-space-2);
+    align-items: center;
+    max-inline-size: 50%;
+    color: var(--plinth-color-text-muted);
+    text-align: end;
+    overflow-wrap: anywhere;
+  }
+
+  .plinth-list-row-chevron {
+    color: var(--plinth-color-text-subtle);
+  }
+
+  .plinth-list-row[aria-current='page'] .plinth-list-row-title {
+    font-weight: var(--plinth-font-weight-medium);
+  }
+
+  @media (forced-colors: active) {
+    .plinth-list-row[aria-current='page'] {
+      color: HighlightText;
+      background-color: Highlight;
+    }
+
+    .plinth-list-row:disabled,
+    .plinth-list-row[aria-disabled='true'] {
+      color: GrayText;
+    }
+  }
+}

package/packages/css/dist/menu-sheet.css

@@ -0,0 +1,84 @@
+/*
+ * Menu sheet: the app shell's menu, a sheet with the signed-in user, the navigation and the
+ * account actions. A side panel from 768px up, a bottom sheet on a phone.
+ *
+ * <dialog id="menu" class="plinth-sheet plinth-menu-sheet" data-side="end"
+ *   data-side-phone="bottom" closedby="any" aria-labelledby="menu-title">
+ *   <div class="plinth-sheet-panel">
+ *     <div class="plinth-sheet-handle" aria-hidden="true"></div>
+ *     <div class="plinth-sheet-header">
+ *       <h2 id="menu-title" class="plinth-sheet-title">Menu</h2>
+ *       <button … class="plinth-button plinth-icon-button plinth-sheet-close" commandfor="menu"
+ *         command="close">…</button>
+ *     </div>
+ *     <div class="plinth-sheet-body">
+ *       <a class="plinth-list-row plinth-menu-sheet-user" href="/profile">
+ *         <span class="plinth-list-row-leading">
+ *           <span class="plinth-avatar" data-size="lg" aria-hidden="true">…</span>
+ *         </span>
+ *         <span class="plinth-list-row-content">
+ *           <span class="plinth-list-row-title">Sam Lee</span>
+ *           <span class="plinth-list-row-description">sam@example.com</span>
+ *         </span>
+ *         <span class="plinth-list-row-trailing">…chevron…</span>
+ *       </a>
+ *       <nav class="plinth-menu-sheet-nav" aria-labelledby="menu-title">
+ *         <div class="plinth-list-card">…link rows, one with aria-current="page"…</div>
+ *       </nav>
+ *       <div class="plinth-menu-sheet-account">
+ *         <div class="plinth-list-card">…Settings, Sign out…</div>
+ *       </div>
+ *     </div>
+ *   </div>
+ * </dialog>
+ *
+ * It is a sheet (sheet.css), always data-side="end" data-side-phone="bottom", with no footer;
+ * everything the sheet's contract says holds, and it needs modal.css, sheet.css, list-row.css, list-card.css, avatar.css,
+ * button.css and icon.css. The root's id is required in practice: the header's menu button opens
+ * it with <button commandfor="menu" command="show-modal">, the close button points at it too, and
+ * the dialog and the nav are named by the title, whose id is the root's id with -title.
+ *
+ * The parts, in the body:
+ * - the user row (optional): a list row with a decorative avatar (lg), the name and an optional
+ *   detail (an email or a role); a static <div>, or a link to the profile with a chevron when it
+ *   has an href. The avatar is decorative because the name is printed next to it.
+ * - the nav (always there): a <nav> named by the sheet's title (aria-labelledby), holding list
+ *   cards of link rows, their headings <h3> under the sheet's <h2> title. The app marks the row
+ *   of the page being shown with aria-current="page" (current on the list row) and keeps it up
+ *   to date; the menu remembers nothing.
+ * - the account (optional): a list card of account actions, such as Settings and Sign out (a
+ *   button row; for a form post, a button row with type="submit" and form="…").
+ *
+ * The parts stack with a gap between them. In the full-height side panel the account sits on the
+ * bottom edge (margin-block-start: auto) and rises with the content when the nav is long; the
+ * body scrolls as one.
+ */
+
+@layer plinth {
+  .plinth-menu-sheet .plinth-sheet-body {
+    display: flex;
+    flex-direction: column;
+    gap: var(--plinth-space-5);
+  }
+
+  .plinth-menu-sheet-nav,
+  .plinth-menu-sheet-account {
+    display: flex;
+    flex-direction: column;
+    gap: var(--plinth-space-5);
+  }
+
+  .plinth-menu-sheet-account {
+    margin-block-start: auto;
+  }
+
+  /* The name reads as the row's heading. */
+  .plinth-menu-sheet-user .plinth-list-row-title {
+    font-weight: var(--plinth-font-weight-medium);
+  }
+
+  /* A link to the profile rounds its hover tint like the list cards' corners below it. */
+  a.plinth-menu-sheet-user {
+    border-radius: var(--plinth-radius-container);
+  }
+}