@cawalch/porchlight 0.1.0

package/src/06-components/stat.css

@@ -0,0 +1,107 @@
+/*
+ * Porchlight  -  stat component
+ * ===========================================================================
+ * A KPI / metric tile  -  the workhorse of SaaS dashboards. Displays a single
+ * number with a label, an optional unit, a trend indicator (up/down/flat), and
+ * an optional sparkline slot. Designed to sit inside .l-grid (auto-fitting
+ * dashboard widgets) or inside .c-card bodies.
+ *
+ * Structure: .c-stat > .c-stat__label + .c-stat__value (+ .c-stat__unit) +
+ * .c-stat__trend + .c-stat__spark. The value uses tabular-nums so numbers
+ * don't jitter when they update. The trend uses semantic colors + an arrow
+ * glyph, not just color (colorblind-safe).
+ *
+ * This is a display component  -  no interactive states. It composes with .c-card
+ * when you need elevation: place .c-stat inside a .c-card for a raised tile.
+ */
+@layer porchlight.components {
+  @scope (.c-stat) {
+    :scope {
+      --c-stat-gap: var(--pl-space-1);
+
+      display: flex;
+      flex-direction: column;
+      gap: var(--pl-space-2);
+    }
+
+    .c-stat__label {
+      font-size: var(--pl-text-sm);
+      font-weight: var(--pl-font-weight-semibold);
+      color: var(--pl-color-text-muted);
+      line-height: 1;
+    }
+
+    .c-stat__value {
+      display: flex;
+      align-items: baseline;
+      gap: var(--pl-space-2);
+      font-size: clamp(1.75rem, 1.5rem + 1vi, 2.25rem);
+      font-weight: var(--pl-font-weight-bold);
+      line-height: var(--pl-leading-tight);
+      color: var(--pl-color-text);
+      font-variant-numeric: tabular-nums;
+      letter-spacing: -0.02em;
+    }
+
+    .c-stat__unit {
+      font-size: var(--pl-text-md);
+      font-weight: var(--pl-font-weight-medium);
+      color: var(--pl-color-text-muted);
+    }
+
+    .c-stat__trend {
+      display: inline-flex;
+      align-items: center;
+      gap: var(--pl-space-1);
+      font-size: var(--pl-text-sm);
+      font-weight: var(--pl-font-weight-semibold);
+      font-variant-numeric: tabular-nums;
+      color: var(--pl-color-text-muted);
+    }
+
+    /* Trend directions  -  semantic colors. The arrow glyph is always present
+       so color is not the sole signal (colorblind-safe). */
+    .c-stat__trend[data-direction="up"] {
+      color: var(--pl-color-success-text);
+    }
+
+    .c-stat__trend[data-direction="down"] {
+      color: var(--pl-color-danger-text);
+    }
+
+    /* The arrow lives in a ::before so app HTML doesn't need a glyph icon. */
+    .c-stat__trend::before {
+      display: inline-block;
+      font-size: 0.7em;
+      line-height: 1;
+    }
+
+    .c-stat__trend[data-direction="up"]::before {
+      content: "▲";
+    }
+
+    .c-stat__trend[data-direction="down"]::before {
+      content: "▼";
+    }
+
+    .c-stat__trend[data-direction="flat"]::before {
+      content: "▶";
+      transform: rotate(-90deg);
+    }
+
+    /* Optional sparkline slot  -  an inline SVG or canvas. */
+    .c-stat__spark {
+      margin-block-start: var(--pl-space-1);
+    }
+  }
+
+  @media (forced-colors: active) {
+    :where(.c-stat__trend)[data-direction="up"] {
+      color: CanvasText;
+    }
+
+    :where(.c-stat__trend)[data-direction="down"] {
+      color: CanvasText;
+    }
+  }
+}

package/src/06-components/stepper.css

@@ -0,0 +1,172 @@
+/*
+ * Porchlight  -  stepper component
+ * ===========================================================================
+ * A horizontal (default) or vertical (container-query collapse) multi-step
+ * indicator. Each step has a visual marker (circle with number or check) and
+ * a label. Connectors between steps are CSS-only (no SVG).
+ *
+ * State is driven by attributes:
+ *   [data-state="completed"]  - done (checkmark, accent fill)
+ *   [data-state="current"]    - active (accent ring, bold label)
+ *   [data-state="upcoming"]   - pending (muted)
+ *
+ * Structure:
+ *   <ol class="c-stepper">
+ *     <li class="c-stepper__step" data-state="completed">
+ *       <span class="c-stepper__marker">1</span>
+ *       <span class="c-stepper__label">Account</span>
+ *     </li>
+ *     <li class="c-stepper__step" data-state="current">
+ *       <span class="c-stepper__marker">2</span>
+ *       <span class="c-stepper__label">Profile</span>
+ *     </li>
+ *     <li class="c-stepper__step" data-state="upcoming">
+ *       <span class="c-stepper__marker">3</span>
+ *       <span class="c-stepper__label">Confirm</span>
+ *     </li>
+ *   </ol>
+ *
+ * Responsive: collapses to vertical below ~36rem container width.
+ */
+@layer porchlight.components {
+  @scope (.c-stepper) {
+    :scope {
+      --c-stepper-marker-size: 2rem;
+      --c-stepper-gap: var(--pl-space-4);
+
+      display: flex;
+      align-items: flex-start;
+      gap: var(--c-stepper-gap);
+      margin: 0;
+      padding: 0;
+      list-style: none;
+    }
+
+    .c-stepper__step {
+      display: flex;
+      flex-direction: column;
+      align-items: center;
+      gap: var(--pl-space-2);
+      flex: 1;
+      position: relative;
+      text-align: center;
+
+      /* Connector line to the next step. */
+      &::before {
+        content: "";
+        position: absolute;
+        inset-block-start: calc(var(--c-stepper-marker-size) / 2);
+        inset-inline: calc(
+            50% + var(--c-stepper-marker-size) / 2 + var(--c-stepper-gap) / 2
+          )
+          calc(
+            -50% + var(--c-stepper-marker-size) / 2 + var(--c-stepper-gap) / 2
+          );
+        block-size: 2px;
+        background: var(--pl-color-border);
+        z-index: var(--pl-z-base);
+      }
+
+      /* No connector after the last step. */
+      &:last-child::before {
+        content: none;
+      }
+    }
+
+    /* Completed step connector: accent fill. */
+    .c-stepper__step[data-state="completed"]::before {
+      background: var(--pl-color-accent);
+    }
+
+    .c-stepper__marker {
+      display: inline-flex;
+      align-items: center;
+      justify-content: center;
+      inline-size: var(--c-stepper-marker-size);
+      block-size: var(--c-stepper-marker-size);
+      border-radius: 50%;
+      border: 2px solid var(--pl-color-border);
+      background: var(--pl-color-surface);
+      color: var(--pl-color-text-muted);
+      font-size: var(--pl-text-sm);
+      font-weight: var(--pl-font-weight-semibold);
+      z-index: var(--pl-z-raised);
+      transition:
+        background-color var(--pl-duration-2) var(--pl-ease-standard),
+        border-color var(--pl-duration-2) var(--pl-ease-standard),
+        color var(--pl-duration-2) var(--pl-ease-standard),
+        box-shadow var(--pl-duration-2) var(--pl-ease-standard);
+    }
+
+    /* Completed: accent fill + white text. */
+    .c-stepper__step[data-state="completed"] .c-stepper__marker {
+      border-color: var(--pl-color-accent);
+      background: var(--pl-color-accent);
+      color: var(--pl-color-accent-text);
+    }
+
+    /* Current: accent ring, bold. */
+    .c-stepper__step[data-state="current"] .c-stepper__marker {
+      border-color: var(--pl-color-accent);
+      color: var(--pl-color-accent);
+      box-shadow: 0 0 0 4px
+        color-mix(in oklab, var(--pl-color-accent), transparent var(--pl-focus-glow-opacity));
+    }
+
+    .c-stepper__label {
+      font-size: var(--pl-text-sm);
+      color: var(--pl-color-text-muted);
+      line-height: var(--pl-leading-snug);
+    }
+
+    .c-stepper__step[data-state="current"] .c-stepper__label {
+      color: var(--pl-color-text);
+      font-weight: var(--pl-font-weight-semibold);
+    }
+
+    /* Container-query collapse to vertical. */
+    @container (max-width: 36rem) {
+      :scope {
+        flex-direction: column;
+        gap: 0;
+      }
+
+      .c-stepper__step {
+        flex-direction: row;
+        align-items: center;
+        flex: none;
+        text-align: start;
+        padding-block-end: var(--pl-space-4);
+
+        &::before {
+          inset-block: var(--c-stepper-marker-size) 0;
+          inset-inline: calc(var(--c-stepper-marker-size) / 2) auto;
+          inline-size: 2px;
+        }
+      }
+    }
+
+    /* Container query context (applied outside @scope). */
+  }
+
+  /* Container query context. */
+  :where(.c-stepper) {
+    container-type: inline-size;
+  }
+
+  @media (forced-colors: active) {
+    :where(.c-stepper__marker) {
+      border-color: ButtonBorder;
+    }
+
+    :where(.c-stepper__step[data-state="completed"] .c-stepper__marker) {
+      border-color: Highlight;
+      background: Highlight;
+      color: HighlightText;
+    }
+
+    :where(.c-stepper__step[data-state="current"] .c-stepper__marker) {
+      border-color: Highlight;
+    }
+  }
+}

package/src/06-components/switch.css

@@ -0,0 +1,138 @@
+/*
+ * Porchlight  -  switch (toggle) component
+ * ===========================================================================
+ * A CSS-only toggle switch built on a native checkbox. No JavaScript for the
+ * toggle itself: <input type="checkbox" role="switch"> + <label>.
+ *
+ * The track and thumb are styled entirely in CSS. The thumb slides via
+ * transition on inset-inline-start. :checked drives the on/off state.
+ * RTL-aware: thumb slides in the correct logical direction automatically.
+ *
+ * Structure:
+ *   <label class="c-switch">
+ *     <input type="checkbox" role="switch" class="c-switch__input" />
+ *     <span class="c-switch__track">
+ *       <span class="c-switch__thumb"></span>
+ *     </span>
+ *     <span class="c-switch__label">Enable feature</span>
+ *   </label>
+ */
+@layer porchlight.components {
+  @scope (.c-switch) {
+    :scope {
+      --c-switch-track-w: 2.75rem;
+      --c-switch-track-h: 1.5rem;
+      --c-switch-thumb: calc(var(--c-switch-track-h) - 0.25rem);
+      --c-switch-gap: var(--pl-space-2);
+      --c-switch-on: var(--pl-color-accent);
+      --c-switch-off: var(--pl-color-surface-2);
+
+      display: inline-flex;
+      align-items: center;
+      gap: var(--c-switch-gap);
+      cursor: pointer;
+      user-select: none;
+    }
+
+    :scope[disabled],
+    :scope:has(.c-switch__input:disabled) {
+      opacity: var(--pl-opacity-disabled);
+      cursor: not-allowed;
+    }
+
+    /* Visually hide the native checkbox (accessible to AT). */
+    .c-switch__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;
+    }
+
+    /* Track: the pill background. */
+    .c-switch__track {
+      position: relative;
+      display: inline-flex;
+      align-items: center;
+      flex-shrink: 0;
+      inline-size: var(--c-switch-track-w);
+      block-size: var(--c-switch-track-h);
+      border-radius: var(--pl-radius-pill);
+      background: var(--c-switch-off);
+
+      /* No border: surface-2 track provides contrast against page bg.
+         forced-colors block below adds ButtonText border for high-contrast mode. */
+      transition: background-color var(--pl-duration-2) var(--pl-ease-standard);
+    }
+
+    /* Thumb: the sliding circle. */
+    .c-switch__thumb {
+      position: absolute;
+      inline-size: var(--c-switch-thumb);
+      block-size: var(--c-switch-thumb);
+      border-radius: 50%;
+      background: var(--pl-color-surface);
+      box-shadow: var(--pl-shadow-1);
+      inset-inline-start: 0.125rem;
+      transition: inset-inline-start var(--pl-duration-2)
+        var(--pl-ease-standard);
+    }
+
+    /* Checked state: track turns accent, thumb slides to the end. */
+    :scope:has(.c-switch__input:checked) .c-switch__track {
+      background: var(--c-switch-on);
+      border-color: transparent;
+    }
+
+    :scope:has(.c-switch__input:checked) .c-switch__thumb {
+      inset-inline-start: calc(
+        var(--c-switch-track-w) - var(--c-switch-thumb) - 0.125rem
+      );
+    }
+
+    /* Focus ring on the track. */
+    :scope:has(.c-switch__input:focus-visible) .c-switch__track {
+      outline: var(--pl-focus-size) solid var(--pl-focus-color);
+      outline-offset: var(--pl-focus-offset);
+    }
+
+    /* Size variants. */
+    :scope[data-size="sm"] {
+      --c-switch-track-w: 2.25rem;
+      --c-switch-track-h: 1.25rem;
+    }
+
+    :scope[data-size="lg"] {
+      --c-switch-track-w: 3.25rem;
+      --c-switch-track-h: 1.75rem;
+    }
+
+    .c-switch__label {
+      font-size: var(--pl-text-sm);
+      color: var(--pl-color-text);
+    }
+  }
+
+  @media (forced-colors: active) {
+    :where(.c-switch__track) {
+      background: ButtonFace;
+      border-color: ButtonText;
+    }
+
+    :where(.c-switch:has(.c-switch__input:checked) .c-switch__track) {
+      background: Highlight;
+    }
+
+    :where(.c-switch__thumb) {
+      background: ButtonText;
+    }
+
+    :where(.c-switch:has(.c-switch__input:checked) .c-switch__thumb) {
+      background: HighlightText;
+    }
+  }
+}

package/src/06-components/tabs.css

@@ -0,0 +1,164 @@
+/*
+ * Porchlight  -  tabs component
+ * ===========================================================================
+ * A tabbed region: a [role="tablist"] of [role="tab"] controls that switch
+ * between [role="tabpanel"]s. The canonical master-detail / settings /
+ * dashboard-sectioning primitive. Wraps real <button> tabs.
+ *
+ * Behaviour (which tab is active) is APP state, not CSS: the app sets
+ * aria-selected on the tab and [hidden] on the inactive panels (exactly as a
+ * real app drives <dialog> via showModal). The framework owns the styling and
+ * the focus indicator; the roving-tabindex keyboard model is documented as the
+ * app's responsibility (arrow/Home/End). This is the same "no JS in the
+ * framework" boundary every interactive component observes.
+ *
+ * The selected indicator is an inset box-shadow on the tab's block-end edge,
+ * NOT a border + negative margin: box-shadow never affects layout, so the tab
+ * never shifts when it becomes selected, and the indicator cleanly overlaps
+ * the tablist's own bottom border.
+ *
+ * State rules follow the @scope rule of thumb: structural + attribute selectors
+ * ([aria-selected], a real attribute) live inside @scope; live-state pseudos
+ * (:hover, :focus-visible) live outside it with :where(), because they don't
+ * reliably apply to scoped descendants.
+ */
+@layer porchlight.components {
+  @scope (.c-tabs) {
+    :scope {
+      --c-tabs-gap: var(--pl-space-4);
+      --c-tabs-indicator: 3px;
+
+      display: grid;
+      gap: var(--c-tabs-gap);
+    }
+
+    .c-tabs__list {
+      display: flex;
+      gap: var(--pl-space-1);
+      padding: 0;
+      margin: 0;
+      list-style: none;
+      border-block-end: 1px solid color-mix(
+        in oklab,
+        var(--pl-color-border),
+        transparent 20%
+      );
+      overflow-x: auto;
+      scrollbar-width: none; /* Hide scrollbar in Firefox */
+
+      &::-webkit-scrollbar {
+        display: none; /* Hide scrollbar in Chrome/Safari */
+      }
+    }
+
+    .c-tabs__tab {
+      --c-tabs-tab-padding: var(--pl-space-3);
+
+      appearance: none;
+      display: inline-flex;
+      align-items: center;
+      flex-shrink: 0;
+      gap: var(--pl-space-2);
+      padding: var(--pl-space-2) var(--c-tabs-tab-padding);
+      border: 0;
+      background: transparent;
+      color: var(--pl-color-text-muted);
+      font: inherit;
+      font-weight: var(--pl-font-weight-medium);
+      white-space: nowrap;
+      cursor: pointer;
+
+      /* The selected indicator: a block-end accent line drawn INSIDE the tab.
+         Transparent unless selected; box-shadow (not border) so selecting a
+         tab never shifts layout. Sits flush over the tablist border. */
+      box-shadow: inset 0 calc(var(--c-tabs-indicator) * -1) 0 0 transparent;
+      transition:
+        color var(--pl-duration-1) var(--pl-ease-standard),
+        box-shadow var(--pl-duration-1) var(--pl-ease-standard);
+    }
+
+    /* Selected: accent text, bolder, and the accent indicator line. */
+    .c-tabs__tab[aria-selected="true"] {
+      color: var(--pl-color-accent);
+      font-weight: var(--pl-font-weight-semibold);
+      box-shadow: inset 0 calc(var(--c-tabs-indicator) * -1) 0 0
+        var(--pl-color-accent);
+    }
+
+    .c-tabs__tab:disabled,
+    .c-tabs__tab[aria-disabled="true"] {
+      color: var(--pl-color-text-muted);
+      opacity: var(--pl-opacity-disabled);
+    }
+
+    /* A trailing count (unread, total) inside a tab  -  a muted chip. */
+    .c-tabs__tab .c-tabs__count {
+      padding-inline: var(--pl-space-2);
+      border-radius: var(--pl-radius-pill);
+      background: var(--pl-color-surface-2);
+      color: var(--pl-color-text-muted);
+      font-size: var(--pl-text-xs);
+      font-weight: var(--pl-font-weight-semibold);
+      line-height: var(--pl-leading-snug);
+    }
+
+    .c-tabs__tab[aria-selected="true"] .c-tabs__count {
+      background: color-mix(in oklab, var(--pl-color-accent), transparent 82%);
+      color: var(--pl-color-accent);
+    }
+
+    /* Panels: block by default; an inactive one is [hidden] in HTML. */
+    .c-tabs__panel {
+      animation: c-tabs-reveal var(--pl-duration-2) var(--pl-ease-standard);
+    }
+  }
+
+  /* Live-state rules OUTSIDE @scope (:hover/:focus-visible on the tab don't
+     reliably apply inside @scope). A subtle surface-2 wash on hover aids
+     discoverability without competing with the selected indicator. */
+  :where(.c-tabs__list)
+    .c-tabs__tab:is(:hover, :focus-visible):not(
+      :disabled,
+      [aria-disabled="true"]
+    ) {
+    background: var(--pl-color-surface-2);
+    color: var(--pl-color-text);
+  }
+
+  /* Hover should NOT fake the accent indicator on an unselected tab  -  only the
+     selected tab carries the line. Restore muted text on hover so colour still
+     flips for affordance without implying selection. */
+  :where(.c-tabs__list)
+    .c-tabs__tab:hover:not(:disabled, [aria-disabled="true"]) {
+    color: var(--pl-color-text);
+  }
+
+  :where(.c-tabs__list) .c-tabs__tab:focus-visible {
+    outline: var(--pl-focus-size) solid var(--pl-focus-color);
+    outline-offset: calc(var(--pl-focus-offset) * -1);
+  }
+
+  /* Reveal animation for a newly-shown panel. Disabled under reduced motion by
+     the themes layer's universal 1ms clamp, so it degrades to an instant cut. */
+  @keyframes c-tabs-reveal {
+    from {
+      opacity: 0;
+      transform: translateY(2px);
+    }
+  }
+
+  @media (forced-colors: active) {
+    :where(.c-tabs__list) {
+      border-block-end-color: CanvasText;
+    }
+
+    :where(.c-tabs__tab)[aria-selected="true"] {
+      color: Highlight;
+      box-shadow: inset 0 calc(var(--c-tabs-indicator) * -1) 0 0 Highlight;
+    }
+
+    :where(.c-tabs__tab):focus-visible {
+      outline-color: Highlight;
+    }
+  }
+}

package/src/06-components/tag-input.css

@@ -0,0 +1,77 @@
+/*
+ * Porchlight  -  tag input component
+ * ===========================================================================
+ * A text input that accepts multiple values as removable chips. The CSS
+ * handles the layout (wrapping chips + inline input); JS handles
+ * tokenization (enter/comma to add, backspace to remove).
+ *
+ * Uses field-sizing: content where supported so the input auto-grows.
+ * Falls back to a fixed-width input.
+ *
+ * Structure:
+ *   <div class="c-tag-input">
+ *     <span class="c-chip">React <button class="c-chip__remove">x</button></span>
+ *     <input class="c-tag-input__field" placeholder="Add tag..." />
+ *   </div>
+ */
+@layer porchlight.components {
+  @scope (.c-tag-input) {
+    :scope {
+      --c-tag-input-pad: var(--pl-space-2);
+      --c-tag-input-gap: var(--pl-space-2);
+      --c-tag-input-min-h: calc(var(--pl-control-block-size) - 2px);
+
+      display: flex;
+      flex-wrap: wrap;
+      align-items: center;
+      gap: var(--c-tag-input-gap);
+      min-block-size: var(--c-tag-input-min-h);
+      padding: var(--c-tag-input-pad);
+      border: 1px solid var(--pl-color-border);
+      border-radius: var(--pl-radius-md);
+      background: var(--pl-color-surface);
+      cursor: text;
+      transition:
+        border-color var(--pl-duration-1) var(--pl-ease-standard),
+        box-shadow var(--pl-duration-1) var(--pl-ease-standard);
+    }
+
+    :scope:focus-within {
+      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));
+    }
+
+    .c-tag-input__field {
+      flex: 1;
+      min-inline-size: 6rem;
+      padding: 0;
+      border: 0;
+      background: transparent;
+      color: inherit;
+      font: inherit;
+      font-size: var(--pl-text-sm);
+      outline: none;
+    }
+
+    .c-tag-input__field::placeholder {
+      color: var(--pl-color-text-muted);
+    }
+
+    /* Auto-grow where supported. */
+    @supports (field-sizing: content) {
+      .c-tag-input__field {
+        field-sizing: content;
+        min-inline-size: 4rem;
+      }
+    }
+  }
+
+  @media (forced-colors: active) {
+    :where(.c-tag-input) {
+      border-color: ButtonBorder;
+      background: Canvas;
+    }
+  }
+}