@cawalch/porchlight 0.1.0

package/src/06-components/pagination.css

@@ -0,0 +1,106 @@
+/*
+ * Porchlight  -  pagination component
+ * ===========================================================================
+ * Navigation control for paginated data  -  the bar below a table or list.
+ * Previous / Next buttons flank a row of page number buttons. A compact
+ * [data-size="sm"] variant shrinks the controls for embedded use (inside a
+ * toolbar or table footer).
+ *
+ * Sizing comes from --pl-control-* tokens (like .c-button), so density and
+ * touch-target rules apply automatically. The active page uses aria-current,
+ * which is the semantic attribute for "you are here" navigation.
+ *
+ * The page buttons reuse .c-button[data-variant="ghost"] styling conventions
+ * (accent wash for the active state) but are self-contained so pagination works
+ * without also loading .c-button. If .c-button IS present, a .c-button inside
+ * the toolbar inherits its own styling  -  the two coexist without conflict.
+ */
+@layer porchlight.components {
+  @scope (.c-pagination) {
+    :scope {
+      --c-pagination-min: var(--pl-control-block-size);
+
+      display: flex;
+      align-items: center;
+      gap: var(--pl-space-1);
+    }
+
+    /* A page button  -  square-ish, ghost-like. */
+    .c-pagination__page,
+    .c-pagination__nav {
+      appearance: none;
+      display: inline-flex;
+      align-items: center;
+      justify-content: center;
+      gap: var(--pl-space-1);
+      min-block-size: var(--c-pagination-min);
+      min-inline-size: var(--c-pagination-min);
+      padding-inline: var(--pl-space-2);
+      border: 1px solid transparent;
+      border-radius: var(--pl-radius-md);
+      background: transparent;
+      color: var(--pl-color-text-muted);
+      font: inherit;
+      font-weight: var(--pl-font-weight-medium);
+      cursor: pointer;
+      transition:
+        background-color var(--pl-duration-1) var(--pl-ease-standard),
+        color var(--pl-duration-1) var(--pl-ease-standard);
+    }
+
+    /* Active page  -  aria-current="page" marks "you are here". */
+    .c-pagination__page[aria-current="page"] {
+      background: var(--pl-color-accent);
+      color: var(--pl-color-accent-text);
+      font-weight: var(--pl-font-weight-semibold);
+    }
+
+    /* Compact variant  -  smaller targets for embedded use (table footers). */
+    :scope[data-size="sm"] {
+      --c-pagination-min: 2rem;
+    }
+
+    .c-pagination__page:disabled,
+    .c-pagination__nav:disabled {
+      opacity: var(--pl-opacity-disabled);
+      cursor: not-allowed;
+    }
+
+    /* Ellipsis  -  a non-interactive spacer for skipped pages. */
+    .c-pagination__ellipsis {
+      display: inline-flex;
+      align-items: center;
+      justify-content: center;
+      min-inline-size: var(--c-pagination-min);
+      color: var(--pl-color-text-muted);
+      user-select: none;
+    }
+  }
+
+  /* Live-state hover OUTSIDE @scope. */
+  :where(.c-pagination__page:not([aria-current="page"])):is(
+    :hover,
+    :focus-visible
+  ) {
+    background: var(--pl-color-surface-2);
+    color: var(--pl-color-text);
+  }
+
+  :where(.c-pagination__page):focus-visible,
+  :where(.c-pagination__nav):focus-visible {
+    outline: var(--pl-focus-size) solid var(--pl-focus-color);
+    outline-offset: calc(var(--pl-focus-offset) * -1);
+  }
+
+  @media (forced-colors: active) {
+    :where(.c-pagination__page)[aria-current="page"] {
+      background: Highlight;
+      color: HighlightText;
+    }
+
+    :where(.c-pagination__page):focus-visible,
+    :where(.c-pagination__nav):focus-visible {
+      outline-color: Highlight;
+    }
+  }
+}

package/src/06-components/popover-menu.css

@@ -0,0 +1,146 @@
+/*
+ * Porchlight  -  popover menu component
+ * ===========================================================================
+ * A dropdown menu anchored to its trigger  -  account menus, action menus,
+ * context menus. Uses the native Popover API (top-layer, light-dismiss,
+ * focus management) + CSS anchor positioning (tethered to the trigger) +
+ * @starting-style for a native enter/exit animation.
+ *
+ * The popover element MUST have the `popover` attribute in HTML:
+ *   <div popover class="c-menu__popover" id="...">...</div>
+ * The trigger uses `popovertarget="id"` to open it declaratively  -  no JS.
+ *
+ * Anchor positioning is @supports-gated: browsers without it fall back to the
+ * UA's default centering; Chrome 149+ positions the popover at the trigger's
+ * block-end / inline-end corner via position-area.
+ *
+ * Multiple menus on one page need unique anchor names  -  set --c-menu-anchor
+ * per instance (defaults to --pl-menu-anchor; works for a single menu).
+ */
+@layer porchlight.components {
+  @scope (.c-menu) {
+    :scope {
+      --c-menu-anchor: --pl-menu-anchor;
+
+      display: inline-block;
+    }
+
+    .c-menu__trigger {
+      anchor-name: var(--c-menu-anchor);
+    }
+
+    .c-menu__popover {
+      margin: 0;
+      padding: var(--pl-space-2);
+      min-inline-size: 12rem;
+
+      /* Floating surface: softened border + Liquid Glass. */
+      border: 1px solid color-mix(
+        in oklab,
+        var(--pl-color-border),
+        transparent 30%
+      );
+      border-radius: var(--pl-radius-xl);
+      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));
+      color: var(--pl-color-text);
+      box-shadow: var(--pl-shadow-3);
+
+      /* Asymmetric motion: enters deliberately, exits snappily. */
+      opacity: 0;
+      transform: translateY(-4px);
+      transition:
+        opacity var(--pl-duration-enter) var(--pl-ease-decelerate),
+        transform var(--pl-duration-enter) var(--pl-ease-decelerate),
+        overlay var(--pl-duration-exit) var(--pl-ease-accelerate) allow-discrete,
+        display var(--pl-duration-exit) var(--pl-ease-accelerate) allow-discrete;
+    }
+
+    /* Anchor positioning  -  tether the popover to the trigger. @supports-gated
+       so browsers without anchor support fall back gracefully. inset: auto
+       resets the UA's default centering for popovers. */
+    @supports (position-anchor: --x) {
+      .c-menu__popover {
+        inset: auto;
+        position: absolute;
+        position-anchor: var(--c-menu-anchor);
+        position-area: block-end span-inline-end;
+        position-try-fallbacks: flip-block;
+        margin-block-start: var(--pl-space-2);
+      }
+    }
+
+    /* Open state: visible + settled. */
+    .c-menu__popover:popover-open {
+      opacity: 1;
+      transform: translateY(0);
+    }
+
+    /* Enter: @starting-style sets the initial state BEFORE the open transition. */
+    @starting-style {
+      .c-menu__popover:popover-open {
+        opacity: 0;
+        transform: translateY(-4px);
+      }
+    }
+
+    .c-menu__divider {
+      margin-block: var(--pl-space-1);
+      border: 0;
+      border-block-start: 1px solid var(--pl-color-border);
+    }
+  }
+
+  /* Menu items  -  OUTSIDE @scope (live-state pseudos :hover/:focus-visible on
+     descendants don't reliably apply inside @scope; same lesson as .c-field).
+     Each item is a full-width <a> or <button> for keyboard access. */
+  :where(.c-menu__popover) > :is(a, button) {
+    display: flex;
+    align-items: center;
+    gap: var(--pl-space-2);
+    inline-size: 100%;
+    min-block-size: 2.25rem;
+    padding-inline: var(--pl-space-3);
+    border: 0;
+    border-radius: var(--pl-radius-sm);
+    background: transparent;
+    color: inherit;
+    font: inherit;
+    text-align: start;
+    text-decoration: none;
+    cursor: pointer;
+  }
+
+  :where(.c-menu__popover) > :is(a, button):is(:hover, :focus-visible) {
+    background: var(--pl-color-surface-2);
+  }
+
+  :where(.c-menu__popover) > :is(a, button):focus-visible {
+    outline: var(--pl-focus-size) solid var(--pl-focus-color);
+    outline-offset: calc(var(--pl-focus-offset) * -1);
+  }
+
+  /* Destructive item  -  sign out, delete. */
+  :where(.c-menu__popover) > :is(a, button)[data-tone="danger"] {
+    color: var(--pl-color-danger-text);
+  }
+
+  :where(.c-menu__popover)
+    > :is(a, button)[data-tone="danger"]:is(:hover, :focus-visible) {
+    background: var(--pl-color-danger-bg);
+  }
+
+  @media (forced-colors: active) {
+    :where(.c-menu__popover) {
+      border-color: ButtonBorder;
+    }
+
+    :where(.c-menu__popover) > :is(a, button):focus-visible {
+      outline-color: Highlight;
+    }
+  }
+}

package/src/06-components/progress.css

@@ -0,0 +1,77 @@
+/*
+ * Porchlight  -  progress bar component
+ * ===========================================================================
+ * A linear progress indicator for task completion, uploads, or capacity.
+ * Determinate ([data-value="65"]) shows a fill proportional to the value;
+ * indeterminate ([data-indeterminate]) shows an animated sweep.
+ *
+ * Tone variants via [data-tone]: default (accent), success, warning, danger.
+ * For multi-segment progress (e.g. storage usage), nest multiple
+ * .c-progress__bar elements with different tones.
+ *
+ * The track is a 4px-high rounded bar; the fill animates width via
+ * transition (respects reduced-motion). The indeterminate animation uses
+ * a keyframe sweep that stops under reduced-motion (themes layer clamp).
+ */
+@layer porchlight.components {
+  @scope (.c-progress) {
+    :scope {
+      --c-progress-tone: var(--pl-color-accent);
+      --c-progress-height: 0.375rem;
+
+      position: relative;
+      overflow: hidden;
+      block-size: var(--c-progress-height);
+      border-radius: var(--pl-radius-pill);
+      background: var(--pl-color-surface-2);
+    }
+
+    .c-progress__bar {
+      block-size: 100%;
+      border-radius: var(--pl-radius-pill);
+      background: var(--c-progress-tone);
+      transition: inline-size var(--pl-duration-3) var(--pl-ease-standard);
+    }
+
+    /* Tone variants. */
+    :scope[data-tone="success"] {
+      --c-progress-tone: var(--pl-color-success);
+    }
+
+    :scope[data-tone="warning"] {
+      --c-progress-tone: var(--pl-color-warning);
+    }
+
+    :scope[data-tone="danger"] {
+      --c-progress-tone: var(--pl-color-danger);
+    }
+
+    /* Indeterminate  -  an animated sweep that loops. */
+    :scope[data-indeterminate] .c-progress__bar {
+      position: absolute;
+      inset-block: 0;
+      inline-size: 40%;
+      animation: c-progress-sweep 1.4s var(--pl-ease-standard) infinite;
+    }
+  }
+
+  @keyframes c-progress-sweep {
+    0% {
+      inset-inline-start: -40%;
+    }
+
+    100% {
+      inset-inline-start: 100%;
+    }
+  }
+
+  @media (forced-colors: active) {
+    :where(.c-progress) {
+      background: CanvasText;
+    }
+
+    :where(.c-progress__bar) {
+      background: Highlight;
+    }
+  }
+}

package/src/06-components/reveal.css

@@ -0,0 +1,73 @@
+/*
+ * Porchlight  -  scroll reveal component
+ * ===========================================================================
+ * Elements that fade/slide in as they enter the viewport. Uses scroll-driven
+ * animations (animation-timeline: view())  -  zero JavaScript, no
+ * IntersectionObserver.
+ *
+ * @supports-gated: where scroll-driven animations are not supported, elements
+ * are always visible (no invisible content).
+ *
+ * Structure:
+ *   <div class="c-reveal">Content that fades in on scroll</div>
+ *
+ * The reveal triggers as the element enters the scrollport, completing when
+ * 30% of it is covered. Use on sections, cards, or images below the fold.
+ *
+ * For varied timing, add [data-delay="1"|"2"|"3"] which shifts the
+ * animation-range start.
+ */
+@layer porchlight.components {
+  /* Scroll-driven reveal. */
+  @supports (animation-timeline: view()) {
+    :where(.c-reveal) {
+      animation: c-reveal-enter both linear;
+      animation-timeline: view();
+      animation-range: entry 0% cover 30%;
+    }
+
+    /* Delay variants: shift the animation range start later. */
+    :where(.c-reveal[data-delay="1"]) {
+      animation-range: entry 10% cover 35%;
+    }
+
+    :where(.c-reveal[data-delay="2"]) {
+      animation-range: entry 20% cover 40%;
+    }
+
+    :where(.c-reveal[data-delay="3"]) {
+      animation-range: entry 30% cover 45%;
+    }
+  }
+
+  /* Without scroll-driven animation support, elements are always visible. */
+  @supports not (animation-timeline: view()) {
+    :where(.c-reveal) {
+      animation: none;
+      opacity: 1;
+      transform: none;
+    }
+  }
+
+  /* Under forced colors, ensure content is always visible (no scroll-gated
+     animations that could leave content invisible in high-contrast mode). */
+  @media (forced-colors: active) {
+    :where(.c-reveal) {
+      animation: none;
+      opacity: 1;
+      transform: none;
+    }
+  }
+
+  @keyframes c-reveal-enter {
+    from {
+      opacity: 0;
+      transform: translateY(1.5rem);
+    }
+
+    to {
+      opacity: 1;
+      transform: translateY(0);
+    }
+  }
+}

package/src/06-components/scroll-progress.css

@@ -0,0 +1,73 @@
+/*
+ * Porchlight  -  scroll progress bar component
+ * ===========================================================================
+ * A fixed bar at the viewport top that fills as the user scrolls the page.
+ * Uses scroll-driven animations (animation-timeline: scroll())  -  zero
+ * JavaScript for the progress tracking.
+ *
+ * @supports-gated: where scroll-driven animations are not supported, the bar
+ * is hidden entirely (no misleading partial fill).
+ *
+ * Structure:
+ *   <div class="c-scroll-progress" data-tone="accent"></div>
+ *
+ * Place at the top of the page (fixed position). Tone variants via [data-tone].
+ * For per-section progress, set animation-timeline to a named scroll
+ * container instead of the root.
+ */
+@layer porchlight.components {
+  /* Scroll-driven progress bar. */
+  @supports (animation-timeline: scroll()) {
+    :where(.c-scroll-progress) {
+      --c-progress-tone: var(--pl-color-accent);
+
+      position: fixed;
+      inset-block-start: 0;
+      inset-inline: 0;
+      z-index: var(--pl-z-sticky);
+      block-size: 4px;
+      transform-origin: inline-start;
+      background: var(--c-progress-tone);
+
+      /* Animate scaleX from 0 to 1 as the page scrolls. */
+      animation: c-scroll-progress-grow auto linear;
+      animation-timeline: scroll(root);
+    }
+
+    :where(.c-scroll-progress[data-tone="success"]) {
+      --c-progress-tone: var(--pl-color-success);
+    }
+
+    :where(.c-scroll-progress[data-tone="warning"]) {
+      --c-progress-tone: var(--pl-color-warning);
+    }
+
+    :where(.c-scroll-progress[data-tone="danger"]) {
+      --c-progress-tone: var(--pl-color-danger);
+    }
+  }
+
+  /* Without scroll-driven animation support, hide the bar. */
+  @supports not (animation-timeline: scroll()) {
+    :where(.c-scroll-progress) {
+      display: none;
+    }
+  }
+
+  /* Under forced colors, use the system highlight color for the bar. */
+  @media (forced-colors: active) {
+    :where(.c-scroll-progress) {
+      background: Highlight;
+    }
+  }
+
+  @keyframes c-scroll-progress-grow {
+    from {
+      transform: scaleX(0);
+    }
+
+    to {
+      transform: scaleX(1);
+    }
+  }
+}

package/src/06-components/segmented.css

@@ -0,0 +1,113 @@
+/*
+ * Porchlight  -  segmented control component
+ * ===========================================================================
+ * A compact inline switcher for binary/ternary toggles (list/grid/table view,
+ * day/week/month). Built on native radio inputs  -  CSS-only, keyboard
+ * accessible, no JavaScript.
+ *
+ * The active segment gets an accent background driven by :has(:checked).
+ * The control is a pill-shaped container with segments as flex children.
+ *
+ * Structure:
+ *   <div class="c-segmented" role="radiogroup" aria-label="View mode">
+ *     <label class="c-segmented__item">
+ *       <input type="radio" name="view" checked />
+ *       <span>List</span>
+ *     </label>
+ *     <label class="c-segmented__item">
+ *       <input type="radio" name="view" />
+ *       <span>Grid</span>
+ *     </label>
+ *   </div>
+ */
+@layer porchlight.components {
+  @scope (.c-segmented) {
+    :scope {
+      --c-segmented-pad: 0.125rem;
+      --c-segmented-gap: var(--pl-space-1);
+      --c-segmented-radius: var(--pl-radius-pill);
+
+      display: inline-flex;
+      gap: var(--c-segmented-gap);
+      padding: var(--c-segmented-pad);
+      border: 1px solid var(--pl-color-border);
+      border-radius: var(--c-segmented-radius);
+      background: var(--pl-color-surface-2);
+    }
+
+    .c-segmented__item {
+      position: relative;
+      display: inline-flex;
+      align-items: center;
+      justify-content: center;
+    }
+
+    /* Visually hide the native radio. */
+    .c-segmented__item input {
+      position: absolute;
+      inline-size: 1px;
+      block-size: 1px;
+      padding: 0;
+      margin: -1px;
+      overflow: hidden;
+      clip: rect(0, 0, 0, 0);
+      white-space: nowrap;
+      border: 0;
+    }
+
+    /* The visible label/pill. */
+    .c-segmented__item span {
+      display: inline-flex;
+      align-items: center;
+      gap: var(--pl-space-1);
+      padding: var(--pl-space-1) var(--pl-space-3);
+      border-radius: var(--c-segmented-radius);
+      color: var(--pl-color-text-muted);
+      font-size: var(--pl-text-sm);
+      font-weight: var(--pl-font-weight-medium);
+      cursor: pointer;
+      user-select: none;
+      white-space: nowrap;
+      transition:
+        background-color var(--pl-duration-1) var(--pl-ease-standard),
+        color var(--pl-duration-1) var(--pl-ease-standard);
+    }
+
+    /* Active segment: accent fill. */
+    .c-segmented__item:has(input:checked) span {
+      background: var(--pl-color-surface);
+      color: var(--pl-color-accent);
+      font-weight: var(--pl-font-weight-semibold);
+      box-shadow: var(--pl-shadow-1);
+    }
+
+    /* Hover on non-checked. */
+    .c-segmented__item:not(:has(input:checked), :has(input:disabled))
+      span:hover {
+      color: var(--pl-color-text);
+    }
+
+    /* Focus ring. */
+    .c-segmented__item:has(input:focus-visible) span {
+      outline: var(--pl-focus-size) solid var(--pl-focus-color);
+      outline-offset: var(--pl-focus-offset);
+    }
+
+    /* Disabled. */
+    .c-segmented__item:has(input:disabled) span {
+      opacity: var(--pl-opacity-disabled);
+      cursor: not-allowed;
+    }
+  }
+
+  @media (forced-colors: active) {
+    :where(.c-segmented) {
+      border-color: ButtonBorder;
+    }
+
+    :where(.c-segmented__item:has(input:checked) span) {
+      background: Highlight;
+      color: HighlightText;
+    }
+  }
+}

package/src/06-components/skeleton.css

@@ -0,0 +1,73 @@
+/*
+ * Porchlight  -  skeleton component
+ * ===========================================================================
+ * Loading placeholders that mimic the shape of real content. A pulsing shimmer
+ * communicates "something is loading" without a spinner (which implies an
+ * indeterminate wait). Used in cards, lists, and tables while data fetches.
+ *
+ * Three shapes via [data-shape]: "text" (a line, default), "circle" (an
+ * avatar), and "rect" (a block). Width is controlled by --c-skeleton-w for
+ * inline sizing; text rows default to 100%.
+ *
+ * The shimmer is a CSS-only animation (opacity pulse). Under reduced motion
+ * the themes layer's universal 1ms clamp stops it; the skeleton remains as a
+ * static grey block (still legible as a placeholder).
+ *
+ * A [data-lines] attribute on a container with .c-skeleton children generates
+ * staggered widths for prose-like placeholder stacks  -  see the preview page.
+ */
+@layer porchlight.components {
+  @scope (.c-skeleton) {
+    :scope {
+      --c-skeleton-w: 100%;
+
+      display: block;
+      inline-size: var(--c-skeleton-w);
+      block-size: var(--pl-text-md);
+      border-radius: var(--pl-radius-sm);
+      background: var(--pl-color-surface-2);
+      animation: c-skeleton-pulse 1.8s var(--pl-ease-standard) infinite;
+    }
+
+    :scope[data-shape="circle"] {
+      inline-size: var(--c-skeleton-w, 2.5rem);
+      block-size: var(--c-skeleton-w, 2.5rem);
+      border-radius: var(--pl-radius-pill);
+    }
+
+    :scope[data-shape="rect"] {
+      block-size: var(--c-skeleton-w, 6rem);
+      inline-size: 100%;
+      border-radius: var(--pl-radius-md);
+    }
+
+    :scope[data-shape="text"][data-line="sm"] {
+      block-size: var(--pl-text-sm);
+    }
+  }
+
+  /* A skeleton group  -  staggered text lines for prose-like placeholders. */
+  :where(.c-skeleton-group) {
+    display: flex;
+    flex-direction: column;
+    gap: var(--pl-space-2);
+  }
+
+  @keyframes c-skeleton-pulse {
+    0%,
+    100% {
+      opacity: 1;
+    }
+
+    50% {
+      opacity: 0.4;
+    }
+  }
+
+  @media (forced-colors: active) {
+    :where(.c-skeleton) {
+      background: CanvasText;
+      opacity: 0.3;
+    }
+  }
+}