@cawalch/porchlight 0.1.0

package/src/06-components/textarea-auto.css

@@ -0,0 +1,77 @@
+/*
+ * Porchlight  -  auto-growing textarea component
+ * ===========================================================================
+ * A textarea that grows to fit its content automatically using
+ * field-sizing: content (Chrome 123+). No JavaScript auto-resize needed.
+ *
+ * @supports-gated: where field-sizing is not supported, the textarea
+ * retains its default rows attribute (graceful degradation to a fixed
+ * height).
+ *
+ * Usage:
+ *   <textarea class="c-textarea-auto" rows="3"></textarea>
+ *
+ * Set [data-max-rows] to cap the growth (CSS can't count rows, so this is
+ * a max-height via the --c-textarea-max-block token).
+ */
+@layer porchlight.components {
+  @scope (.c-textarea-auto) {
+    :scope {
+      --c-textarea-max-block: 24rem;
+
+      inline-size: 100%;
+      padding: var(--pl-space-3);
+      border: 1px solid var(--pl-color-border);
+      border-radius: var(--pl-radius-md);
+      background: var(--pl-color-surface);
+      color: var(--pl-color-text);
+      font: inherit;
+      font-size: var(--pl-text-sm);
+      line-height: var(--pl-leading-normal);
+      resize: vertical;
+      transition:
+        border-color var(--pl-duration-1) var(--pl-ease-standard),
+        box-shadow var(--pl-duration-1) var(--pl-ease-standard);
+    }
+
+    :scope:focus-visible {
+      outline: none;
+      border-color: var(--pl-focus-color);
+      box-shadow: 0 0 0 4px
+        color-mix(in oklab, var(--pl-focus-color), transparent var(--pl-focus-glow-opacity));
+    }
+
+    :scope:user-invalid {
+      border-color: var(--pl-color-danger);
+      box-shadow: 0 0 0 4px
+        color-mix(in oklab, var(--pl-color-danger), transparent var(--pl-focus-glow-opacity));
+    }
+
+    :scope:disabled {
+      opacity: var(--pl-opacity-disabled);
+    }
+
+    /* Auto-grow: field-sizing: content. */
+    @supports (field-sizing: content) {
+      :scope {
+        field-sizing: content;
+
+        /* Cap the growth so very long text scrolls instead of growing
+           indefinitely. */
+        max-block-size: var(--c-textarea-max-block);
+        overflow-y: auto;
+      }
+    }
+  }
+
+  @media (forced-colors: active) {
+    :where(.c-textarea-auto) {
+      border-color: ButtonBorder;
+      background: Canvas;
+    }
+
+    :where(.c-textarea-auto:focus-visible) {
+      outline-color: Highlight;
+    }
+  }
+}

package/src/06-components/timeline.css

@@ -0,0 +1,129 @@
+/*
+ * Porchlight  -  timeline component
+ * ===========================================================================
+ * A vertical activity feed with markers, connector lines, and per-item
+ * content. Each item has a dot/marker on a vertical line, with the content
+ * to the side.
+ *
+ * Structure:
+ *   <ol class="c-timeline">
+ *     <li class="c-timeline__item">
+ *       <span class="c-timeline__dot"></span>
+ *       <div class="c-timeline__content">
+ *         <div class="c-timeline__header">
+ *           <span class="c-timeline__title">Event title</span>
+ *           <time class="c-timeline__time">2 hours ago</time>
+ *         </div>
+ *         <p class="c-timeline__body">Description</p>
+ *       </div>
+ *     </li>
+ *   </ol>
+ *
+ * Tone variants on the dot: [data-tone] on .c-timeline__item.
+ */
+@layer porchlight.components {
+  @scope (.c-timeline) {
+    :scope {
+      --c-timeline-dot-size: 0.75rem;
+      --c-timeline-line-color: var(--pl-color-border);
+      --c-timeline-gap: var(--pl-space-4);
+
+      display: flex;
+      flex-direction: column;
+      margin: 0;
+
+      /* Inline-start padding accounts for the dot's box-shadow ring which
+         extends 2px past the first grid column. Without this, a scrollable
+         timeline (overflow-y:auto forces overflow-x:auto per spec) clips
+         the ring. Inline-end stays 0 so the scrollbar sits flush. */
+      padding-inline: var(--pl-space-1) 0;
+      list-style: none;
+    }
+
+    .c-timeline__item {
+      display: grid;
+      grid-template-columns: var(--c-timeline-dot-size) 1fr;
+      gap: var(--c-timeline-gap);
+      padding-block-end: var(--pl-space-5);
+      position: relative;
+    }
+
+    /* Vertical connector line: drawn on the dot column. */
+    .c-timeline__item:not(:last-child)::before {
+      content: "";
+      position: absolute;
+      inset-block: var(--c-timeline-dot-size) 0;
+      inset-inline-start: calc(var(--c-timeline-dot-size) / 2);
+      inline-size: 2px;
+      background: var(--c-timeline-line-color);
+      transform: translateX(-50%);
+    }
+
+    .c-timeline__dot {
+      inline-size: var(--c-timeline-dot-size);
+      block-size: var(--c-timeline-dot-size);
+      border-radius: 50%;
+      background: var(--pl-color-accent);
+      border: 2px solid var(--pl-color-surface);
+      box-shadow: 0 0 0 2px var(--pl-color-accent);
+      margin-block-start: 0.1875rem;
+      z-index: var(--pl-z-raised);
+    }
+
+    /* Tone variants on the dot. */
+    .c-timeline__item[data-tone="success"] .c-timeline__dot {
+      background: var(--pl-color-success);
+      box-shadow: 0 0 0 2px var(--pl-color-success);
+    }
+
+    .c-timeline__item[data-tone="warning"] .c-timeline__dot {
+      background: var(--pl-color-warning);
+      box-shadow: 0 0 0 2px var(--pl-color-warning);
+    }
+
+    .c-timeline__item[data-tone="danger"] .c-timeline__dot {
+      background: var(--pl-color-danger);
+      box-shadow: 0 0 0 2px var(--pl-color-danger);
+    }
+
+    .c-timeline__content {
+      min-inline-size: 0;
+    }
+
+    .c-timeline__header {
+      display: flex;
+      align-items: baseline;
+      justify-content: space-between;
+      gap: var(--pl-space-2);
+      margin-block-end: var(--pl-space-1);
+    }
+
+    .c-timeline__title {
+      font-size: var(--pl-text-sm);
+      font-weight: var(--pl-font-weight-semibold);
+    }
+
+    .c-timeline__time {
+      font-size: var(--pl-text-xs);
+      color: var(--pl-color-text-muted);
+      white-space: nowrap;
+    }
+
+    .c-timeline__body {
+      font-size: var(--pl-text-sm);
+      color: var(--pl-color-text-muted);
+      line-height: var(--pl-leading-normal);
+    }
+  }
+
+  @media (forced-colors: active) {
+    :where(.c-timeline__dot) {
+      background: Highlight;
+      box-shadow: 0 0 0 2px Highlight;
+    }
+
+    :where(.c-timeline__item:not(:last-child))::before {
+      background: ButtonBorder;
+    }
+  }
+}

package/src/06-components/toast.css

@@ -0,0 +1,175 @@
+/*
+ * Porchlight  -  toast notification component
+ * ===========================================================================
+ * A transient notification that slides in from a screen edge. Unlike alerts
+ * (inline), toasts are overlay-level and auto-dismiss (via JS timer; the CSS
+ * handles the visual entrance/exit).
+ *
+ * Uses @starting-style for the enter animation. The toast stack is a fixed-
+ * position flex column at the bottom-corner of the screen.
+ *
+ * Structure:
+ *   <div class="c-toast-stack" role="region" aria-label="Notifications">
+ *     <div class="c-toast" data-tone="success" role="status">
+ *       <span class="c-toast__icon">...</span>
+ *       <div class="c-toast__content">
+ *         <span class="c-toast__title">Saved</span>
+ *         <span class="c-toast__body">Changes were saved.</span>
+ *       </div>
+ *       <button class="c-toast__close" aria-label="Dismiss">x</button>
+ *     </div>
+ *   </div>
+ *
+ * Tones: default (info), success, warning, danger.
+ * z-index: --pl-z-toast (1100, above overlays/dialogs at 1000).
+ */
+@layer porchlight.components {
+  /* Toast stack: fixed positioning, bottom-corner. */
+  :where(.c-toast-stack) {
+    position: fixed;
+    inset-block-end: var(--pl-space-4);
+    inset-inline-end: var(--pl-space-4);
+    z-index: var(--pl-z-toast);
+    display: flex;
+    flex-direction: column;
+    gap: var(--pl-space-2);
+    inline-size: min(24rem, calc(100vi - 2 * var(--pl-space-4)));
+
+    /* Prevent the stack from stealing pointer events in empty areas. */
+    pointer-events: none;
+  }
+
+  @scope (.c-toast) {
+    :scope {
+      --c-toast-tone: var(--pl-color-accent);
+      --c-toast-pad: var(--pl-space-3) var(--pl-space-4);
+      --c-toast-radius: var(--pl-radius-xl);
+      --c-toast-gap: var(--pl-space-3);
+
+      display: grid;
+      grid-template-columns: auto 1fr auto;
+      gap: var(--c-toast-gap);
+      align-items: start;
+      padding: var(--c-toast-pad);
+
+      /* Floating surface: softened border + Liquid Glass. */
+      border: 1px solid color-mix(
+        in oklab,
+        var(--pl-color-border),
+        transparent 25%
+      );
+      border-inline-start: var(--pl-accent-bar-width) solid var(--c-toast-tone);
+      border-radius: var(--c-toast-radius);
+      background: light-dark(
+        oklch(100% 0 0deg / 96%),
+        oklch(17% 0.04 250deg / 94%)
+      );
+      backdrop-filter: blur(var(--pl-backdrop-blur)) saturate(var(--pl-backdrop-saturate));
+      -webkit-backdrop-filter: blur(var(--pl-backdrop-blur)) saturate(var(--pl-backdrop-saturate));
+      box-shadow: var(--pl-shadow-3);
+      pointer-events: auto;
+
+      /* Enter animation: slide in from the right + fade.
+         Asymmetric: enters deliberately, exits by JS removing [data-visible]. */
+      opacity: 0;
+      transform: translateX(100%);
+      transition:
+        opacity var(--pl-duration-enter) var(--pl-ease-decelerate),
+        transform var(--pl-duration-enter) var(--pl-ease-decelerate);
+
+      /* Use @starting-style so the initial render animates from hidden. */
+      interpolate-size: allow-keywords;
+    }
+
+    /* Settled state (after enter). */
+    :scope[data-visible] {
+      opacity: 1;
+      transform: translateX(0);
+    }
+
+    @starting-style {
+      :scope[data-visible] {
+        opacity: 0;
+        transform: translateX(100%);
+      }
+    }
+
+    /* Tone variants. */
+    :scope[data-tone="success"] {
+      --c-toast-tone: var(--pl-color-success);
+    }
+
+    :scope[data-tone="warning"] {
+      --c-toast-tone: var(--pl-color-warning);
+    }
+
+    :scope[data-tone="danger"] {
+      --c-toast-tone: var(--pl-color-danger);
+    }
+
+    .c-toast__icon {
+      display: flex;
+      align-items: flex-start;
+      color: var(--c-toast-tone);
+      flex-shrink: 0;
+    }
+
+    .c-toast__icon svg {
+      inline-size: 1.25rem;
+      block-size: 1.25rem;
+    }
+
+    .c-toast__content {
+      display: flex;
+      flex-direction: column;
+      gap: var(--pl-space-1);
+      min-inline-size: 0;
+    }
+
+    .c-toast__title {
+      font-weight: var(--pl-font-weight-semibold);
+      font-size: var(--pl-text-sm);
+    }
+
+    .c-toast__body {
+      font-size: var(--pl-text-sm);
+      color: var(--pl-color-text-muted);
+    }
+
+    .c-toast__close {
+      display: inline-flex;
+      align-items: center;
+      justify-content: center;
+      inline-size: 1.5rem;
+      block-size: 1.5rem;
+      padding: 0;
+      border: 0;
+      border-radius: var(--pl-radius-sm);
+      background: transparent;
+      color: var(--pl-color-text-muted);
+      cursor: pointer;
+      flex-shrink: 0;
+      transition: background-color var(--pl-duration-1) var(--pl-ease-standard);
+    }
+
+    .c-toast__close:hover {
+      background: var(--pl-color-surface-2);
+    }
+
+    .c-toast__close:focus-visible {
+      outline: var(--pl-focus-size) solid var(--pl-focus-color);
+      outline-offset: var(--pl-focus-offset);
+    }
+  }
+
+  @media (forced-colors: active) {
+    :where(.c-toast) {
+      border-color: ButtonBorder;
+      background: Canvas;
+    }
+
+    :where(.c-toast__close:focus-visible) {
+      outline-color: Highlight;
+    }
+  }
+}

package/src/06-components/toolbar.css

@@ -0,0 +1,87 @@
+/*
+ * Porchlight  -  toolbar component
+ * ===========================================================================
+ * A horizontal bar grouping actions above a data region  -  the SaaS "action bar"
+ * on top of tables, lists, and canvases. Pairs a leading cluster (search,
+ * filters, bulk actions) with a trailing cluster (primary actions, overflow
+ * menu). On narrow containers the two halves wrap independently.
+ *
+ * Pure structural styling (flex + gap + a divider). It composes .c-button,
+ * .c-field, and .c-menu  -  it is NOT a button system. The toolbar's job is
+ * alignment and wrapping; the components inside provide their own visuals.
+ *
+ * Container-query aware: padding and gap tighten when the toolbar itself is
+ * narrow (inside a split pane), not when the viewport changes.
+ */
+@layer porchlight.components {
+  @scope (.c-toolbar) {
+    :scope {
+      --c-toolbar-gap: var(--pl-space-3);
+      --c-toolbar-pad: var(--pl-space-3);
+      --c-toolbar-min: 10rem;
+
+      container: c-toolbar / inline-size;
+      display: flex;
+      flex-wrap: wrap;
+      align-items: center;
+      justify-content: space-between;
+      gap: var(--c-toolbar-gap);
+      padding: var(--c-toolbar-pad);
+      border-block-end: 1px solid color-mix(
+        in oklab,
+        var(--pl-color-border),
+        transparent 20%
+      );
+      background: var(--pl-color-surface);
+    }
+
+    /* Leading group  -  search, filters, selection count. Grows to fill. */
+    .c-toolbar__group {
+      display: flex;
+      flex-wrap: wrap;
+      align-items: center;
+      gap: var(--pl-space-2);
+      min-inline-size: var(--c-toolbar-min);
+
+      /* The first group can grow to push the trailing group to the right. */
+      flex: 1 1 auto;
+    }
+
+    /* Trailing group (last-child)  -  primary actions, pagination, overflow. */
+    .c-toolbar__group:last-child {
+      justify-content: flex-end;
+      flex: 0 1 auto;
+    }
+
+    /* A divider between toolbar items  -  a thin vertical rule. */
+    .c-toolbar__divider {
+      flex-shrink: 0;
+      inline-size: 1px;
+      block-size: 1.5rem;
+      align-self: center;
+      background: color-mix(
+        in oklab,
+        var(--pl-color-border),
+        transparent 20%
+      );
+    }
+
+    /* Tighten padding when the toolbar is narrow (container query). */
+    @container c-toolbar (inline-size < 36rem) {
+      :scope {
+        --c-toolbar-pad: var(--pl-space-2);
+        --c-toolbar-gap: var(--pl-space-2);
+      }
+    }
+  }
+
+  @media (forced-colors: active) {
+    :where(.c-toolbar) {
+      border-block-end-color: CanvasText;
+    }
+
+    :where(.c-toolbar__divider) {
+      background: CanvasText;
+    }
+  }
+}

package/src/06-components/tooltip.css

@@ -0,0 +1,104 @@
+/*
+ * Porchlight  -  tooltip component
+ * ===========================================================================
+ * A hover/focus tooltip anchored to its trigger using CSS Anchor Positioning.
+ * Zero JavaScript for positioning. Auto-flips when near viewport edges via
+ * position-try-fallbacks.
+ *
+ * The tooltip appears on :hover and :focus-visible of the trigger. It is
+ * tethered via anchor-name/position-anchor. Without anchor positioning
+ * support (@supports gate), the tooltip is hidden (no misleading placement).
+ *
+ * Structure: .c-tooltip wraps a trigger element. The tooltip body is a child
+ * with role="tooltip" and an id referenced by aria-describedby on the trigger.
+ *
+ *   <span class="c-tooltip">
+ *     <span class="c-tooltip__trigger">
+ *       <button aria-describedby="tip-1">Help</button>
+ *     </span>
+ *     <span class="c-tooltip__body" role="tooltip" id="tip-1">Tooltip text</span>
+ *   </span>
+ *
+ * Each instance needs a unique anchor name  -  set --c-tooltip-anchor.
+ */
+@layer porchlight.components {
+  @scope (.c-tooltip) {
+    :scope {
+      --c-tooltip-anchor: --pl-tooltip-anchor;
+      --c-tooltip-bg: var(--pl-color-text);
+      --c-tooltip-text: var(--pl-color-bg);
+      --c-tooltip-pad: var(--pl-space-2) var(--pl-space-3);
+      --c-tooltip-radius: var(--pl-radius-lg);
+      --c-tooltip-font-size: var(--pl-text-sm);
+      --c-tooltip-max-inline: 20rem;
+
+      display: inline-flex;
+      position: relative;
+    }
+
+    .c-tooltip__trigger {
+      anchor-name: var(--c-tooltip-anchor);
+      display: inline-flex;
+    }
+
+    .c-tooltip__body {
+      display: none;
+      opacity: 0;
+      pointer-events: none;
+      position: absolute;
+      padding: var(--c-tooltip-pad);
+      border-radius: var(--c-tooltip-radius);
+      background: var(--c-tooltip-bg);
+      color: var(--c-tooltip-text);
+      font-size: var(--c-tooltip-font-size);
+      line-height: var(--pl-leading-tight);
+      max-inline-size: var(--c-tooltip-max-inline);
+      text-wrap: balance;
+      box-shadow: var(--pl-shadow-2);
+      z-index: var(--pl-z-overlay);
+      transition:
+        opacity var(--pl-duration-1) var(--pl-ease-standard),
+        display var(--pl-duration-1) var(--pl-ease-standard) allow-discrete;
+    }
+
+    /* Anchor positioning: tether above the trigger, try flipping below. */
+    @supports (position-anchor: --x) {
+      .c-tooltip__body {
+        position-anchor: var(--c-tooltip-anchor);
+        position-area: block-start span-inline-end;
+        margin-block-end: var(--pl-space-2);
+        position-try-fallbacks: flip-block;
+      }
+    }
+
+    /* Show on trigger hover/focus. */
+    :scope:has(.c-tooltip__trigger:hover) .c-tooltip__body,
+    :scope:has(.c-tooltip__trigger:focus-visible) .c-tooltip__body {
+      opacity: 1;
+      display: block;
+    }
+
+    /* Enter animation. */
+    @starting-style {
+      :scope:has(.c-tooltip__trigger:hover) .c-tooltip__body,
+      :scope:has(.c-tooltip__trigger:focus-visible) .c-tooltip__body {
+        opacity: 0;
+      }
+    }
+  }
+
+  /* Without anchor positioning support, hide the tooltip body entirely. */
+  @supports not (position-anchor: --x) {
+    :where(.c-tooltip__body) {
+      display: none;
+    }
+  }
+
+  @media (forced-colors: active) {
+    :where(.c-tooltip__body) {
+      background: CanvasText;
+      color: Canvas;
+      border: 1px solid CanvasText;
+    }
+  }
+}

package/src/07-utilities.css

@@ -0,0 +1,77 @@
+/*
+ * Porchlight: utilities
+ * ===========================================================================
+ * A small, finite set of single-purpose helpers for repeated a11y, layout,
+ * and typography needs. NOT a utility-first framework: there is deliberately
+ * no utility for every CSS property. Each utility earns its place by serving
+ * a recurring need a component shouldn't own.
+ *
+ * Allow-list for !important: utilities is the SECOND place it's permitted
+ * (after reset [hidden] and themes reduced-motion). .u-visually-hidden uses it
+ * because the rule MUST win over any component/context. Hiding text from
+ * sighted users while keeping it for AT is an a11y guarantee that can't be
+ * accidentally overridden.
+ *
+ * Naming: .u-* (utility); --u-* are instance-config tokens (e.g. --u-flow-space).
+ */
+@layer porchlight.utilities {
+  /* Visually hide content while keeping it available to assistive tech (the
+     canonical sr-only pattern). The element collapses to a 1px box, is clipped,
+     and is removed from the flow. Used for icon-only buttons, skip links, etc. */
+  :where(.u-visually-hidden) {
+    position: absolute !important;
+    inline-size: 1px !important;
+    block-size: 1px !important;
+    padding: 0 !important;
+    margin: -1px !important;
+    overflow: hidden !important;
+    clip-path: inset(50%) !important;
+    white-space: nowrap !important;
+    border: 0 !important;
+  }
+
+  /* Restore visibility (overrides .u-visually-hidden when focused/active). */
+  :where(.u-visually-hidden:focus, .u-visually-hidden:active) {
+    position: static !important;
+    inline-size: auto !important;
+    block-size: auto !important;
+    clip-path: none !important;
+    white-space: normal !important;
+    margin: 0 !important;
+  }
+
+  /* One-line truncation: table cells, breadcrumb items, file names. */
+  :where(.u-truncate) {
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  /* Vertical rhythm for prose blocks. The sibling selector adds space
+     between top-level children, not before the first / after the last. Tune
+     via --u-flow-space. */
+  :where(.u-flow) > * + * {
+    margin-block-start: var(--u-flow-space, var(--pl-space-4));
+  }
+
+  /* A surface treatment for ad-hoc grouping (not a full .c-card): bg, text,
+     border, radius. For when you need panel styling without a component. */
+  :where(.u-surface) {
+    background: var(--pl-color-surface);
+    color: var(--pl-color-text);
+    border: 1px solid var(--pl-color-border);
+    border-radius: var(--pl-radius-lg);
+  }
+
+  /* Muted text: secondary/caption copy. */
+  :where(.u-muted) {
+    color: var(--pl-color-text-muted);
+  }
+
+  /* Full-bleed: break an element out to the viewport edges inside a
+     constrained container (e.g. a wide table or image in a prose column). */
+  :where(.u-full-bleed) {
+    inline-size: 100vi;
+    margin-inline: calc(50% - 50vi);
+  }
+}