@cawalch/porchlight 0.1.0

package/src/06-components/dropdown.css

@@ -0,0 +1,180 @@
+/*
+ * Porchlight  -  dropdown component
+ * ===========================================================================
+ * A custom select replacement using the Popover API + anchor positioning.
+ * Unlike native <select>, this supports icons, descriptions, multi-select,
+ * and fully custom option rendering.
+ *
+ * The trigger uses popovertarget to open declaratively. The menu is anchored
+ * to the trigger. Options are <button> or <a> elements for keyboard access.
+ *
+ * Structure:
+ *   <div class="c-dropdown">
+ *     <button class="c-dropdown__trigger" popovertarget="dd-1">
+ *       Choose... <svg class="c-dropdown__chevron">...</svg>
+ *     </button>
+ *     <div popover class="c-dropdown__menu" id="dd-1">
+ *       <button class="c-dropdown__option" aria-selected="true">Option A</button>
+ *       <button class="c-dropdown__option">Option B</button>
+ *     </div>
+ *   </div>
+ */
+@layer porchlight.components {
+  @scope (.c-dropdown) {
+    :scope {
+      --c-dropdown-anchor: --pl-dropdown-anchor;
+      --c-dropdown-min-inline: 12rem;
+      --c-dropdown-max-block: 20rem;
+
+      display: inline-block;
+      position: relative;
+    }
+
+    .c-dropdown__trigger {
+      display: inline-flex;
+      align-items: center;
+      gap: var(--pl-space-2);
+      inline-size: 100%;
+      min-block-size: var(--pl-control-block-size);
+      padding-inline: var(--pl-control-padding-inline);
+      border: 1px solid var(--pl-color-border);
+      border-radius: var(--pl-control-radius);
+      background: var(--pl-color-surface);
+      color: var(--pl-color-text);
+      font: inherit;
+      font-size: var(--pl-text-sm);
+      text-align: start;
+      cursor: pointer;
+      anchor-name: var(--c-dropdown-anchor);
+      transition: border-color var(--pl-duration-1) var(--pl-ease-standard);
+    }
+
+    .c-dropdown__trigger:hover {
+      border-color: var(--pl-color-accent);
+    }
+
+    .c-dropdown__trigger:focus-visible {
+      outline: var(--pl-focus-size) solid var(--pl-focus-color);
+      outline-offset: var(--pl-focus-offset);
+    }
+
+    .c-dropdown__chevron {
+      inline-size: 1rem;
+      block-size: 1rem;
+      margin-inline-start: auto;
+      color: var(--pl-color-text-muted);
+      flex-shrink: 0;
+      transition: rotate var(--pl-duration-2) var(--pl-ease-standard);
+    }
+
+    .c-dropdown__trigger:has(~ .c-dropdown__menu:popover-open)
+      .c-dropdown__chevron {
+      rotate: 180deg;
+    }
+
+    .c-dropdown__menu {
+      margin: 0;
+      padding: var(--pl-space-2);
+      min-inline-size: var(--c-dropdown-min-inline);
+      max-block-size: var(--c-dropdown-max-block);
+      overflow-y: auto;
+
+      /* 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));
+      box-shadow: var(--pl-shadow-3);
+
+      /* Asymmetric motion. */
+      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;
+    }
+
+    @supports (position-anchor: --x) {
+      .c-dropdown__menu {
+        inset: auto;
+        position: absolute;
+        position-anchor: var(--c-dropdown-anchor);
+        position-area: block-end span-inline-end;
+        position-try-fallbacks: flip-block;
+        margin-block-start: var(--pl-space-1);
+      }
+    }
+
+    .c-dropdown__menu:popover-open {
+      opacity: 1;
+      transform: translateY(0);
+    }
+
+    @starting-style {
+      .c-dropdown__menu:popover-open {
+        opacity: 0;
+        transform: translateY(-4px);
+      }
+    }
+  }
+
+  /* Dropdown options  -  OUTSIDE @scope (live-state pseudos). */
+  :where(.c-dropdown__menu) > :is(a, button, [role="option"]) {
+    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;
+    font-size: var(--pl-text-sm);
+    text-align: start;
+    text-decoration: none;
+    cursor: pointer;
+  }
+
+  :where(.c-dropdown__menu)
+    > :is(a, button, [role="option"]):is(:hover, :focus-visible) {
+    background: var(--pl-color-surface-2);
+  }
+
+  :where(.c-dropdown__menu) > :is(a, button, [role="option"]):focus-visible {
+    outline: var(--pl-focus-size) solid var(--pl-focus-color);
+    outline-offset: calc(var(--pl-focus-offset) * -1);
+  }
+
+  /* Selected option: accent color + subtle tint background for clarity. */
+  :where(.c-dropdown__menu) > [aria-selected="true"] {
+    color: var(--pl-color-accent);
+    font-weight: var(--pl-font-weight-semibold);
+    background: color-mix(in oklab, var(--pl-color-accent), transparent 92%);
+  }
+
+  @media (forced-colors: active) {
+    :where(.c-dropdown__trigger) {
+      border-color: ButtonBorder;
+    }
+
+    :where(.c-dropdown__menu) {
+      border-color: ButtonBorder;
+    }
+
+    :where(.c-dropdown__menu) > :is(a, button):focus-visible {
+      outline-color: Highlight;
+    }
+  }
+}

package/src/06-components/empty-state.css

@@ -0,0 +1,85 @@
+/*
+ * Porchlight  -  empty state component
+ * ===========================================================================
+ * The "no data yet" placeholder  -  what users see in a table, list, or chart
+ * before there is anything to show. A centered illustration or icon, a title,
+ * a description, and an optional call-to-action. The psychological anchor that
+ * turns a blank screen into an invitation.
+ *
+ * Structure: .c-empty > .c-empty__media (icon/illustration) + .c-empty__title
+ * + .c-empty__description + .c-empty__actions. All slots except the title are
+ * optional. Token-driven; centered via grid for robust vertical centering.
+ *
+ * Tone variants via [data-tone]: default (neutral), "danger" (error states),
+ * "success" (completed/empty-by-design). The media gets the tone color.
+ */
+@layer porchlight.components {
+  @scope (.c-empty) {
+    :scope {
+      --c-empty-pad: var(--pl-space-8);
+      --c-empty-tone: var(--pl-color-text-muted);
+
+      display: grid;
+      justify-items: center;
+      gap: var(--pl-space-3);
+      padding: var(--c-empty-pad);
+      text-align: center;
+      color: var(--pl-color-text-muted);
+    }
+
+    .c-empty__media {
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      inline-size: var(--c-empty-media-size, 3rem);
+      block-size: var(--c-empty-media-size, 3rem);
+      color: var(--c-empty-tone);
+      opacity: 0.6;
+    }
+
+    .c-empty__media svg,
+    .c-empty__media img {
+      inline-size: 100%;
+      block-size: 100%;
+    }
+
+    .c-empty__title {
+      margin: 0;
+      font-size: var(--pl-text-lg);
+      font-weight: var(--pl-font-weight-semibold);
+      color: var(--pl-color-text);
+      text-wrap: balance;
+    }
+
+    .c-empty__description {
+      max-inline-size: 36ch;
+      margin: 0;
+      font-size: var(--pl-text-sm);
+      text-wrap: pretty;
+    }
+
+    .c-empty__actions {
+      display: flex;
+      flex-wrap: wrap;
+      align-items: center;
+      justify-content: center;
+      gap: var(--pl-space-2);
+      margin-block-start: var(--pl-space-2);
+    }
+
+    /* Tone variants  -  recolor the media. */
+    :scope[data-tone="danger"] {
+      --c-empty-tone: var(--pl-color-danger);
+    }
+
+    :scope[data-tone="success"] {
+      --c-empty-tone: var(--pl-color-success);
+    }
+  }
+
+  @media (forced-colors: active) {
+    :where(.c-empty__media) {
+      color: CanvasText;
+    }
+  }
+}

package/src/06-components/field.css

@@ -0,0 +1,125 @@
+/*
+ * Porchlight  -  field component
+ * ===========================================================================
+ * A labeled form control: label, native input, and hint. Wraps native
+ * <input>/<select>/<textarea> so we inherit all their behavior (constraint
+ * validation, autofill, IME, autofill). No JS, no custom widgets.
+ *
+ * State is driven entirely by native pseudos: :focus-visible, :user-invalid,
+ * :disabled. Focus draws a token-colored border AND a 2px ring (box-shadow);
+ * invalid flips the border to danger and the hint to danger-text. State rules
+ * live OUTSIDE @scope  -  :focus-visible / :user-invalid inside @scope (.c-field)
+ * did not reliably apply to the focused control. They stay in the same layer,
+ * with :where() for low specificity.
+ *
+ * Token-driven via --c-field-* aliases. Density comes from --pl-control-*
+ * (set [data-density] on an ancestor).
+ *
+ * Modern CSS: :user-invalid (Baseline 2024) replaces
+ * :invalid:not(:placeholder-shown). accent-color themes native checkbox/radio/color.
+ */
+@layer porchlight.components {
+  @scope (.c-field) {
+    :scope {
+      --c-field-border: var(--pl-color-border);
+      --c-field-bg: var(--pl-color-surface);
+      --c-field-fg: var(--pl-color-text);
+
+      display: grid;
+      gap: var(--pl-space-2);
+      color: var(--c-field-fg);
+    }
+
+    .c-field__label {
+      font-size: var(--pl-text-sm);
+      font-weight: var(--pl-font-weight-semibold);
+
+      /* Logical "for" association: clicking the label focuses the input it wraps. */
+    }
+
+    .c-field__control {
+      /* appearance: none  -  we fully restyle the control; the UA's native
+         input chrome (including its :focus border ring) would otherwise win
+         over our border-color/box-shadow and freeze the border at the UA gray. */
+      appearance: none;
+      inline-size: 100%;
+      min-block-size: var(--pl-control-block-size);
+
+      /* Vertical padding is token-derived so the control height stays within
+         --pl-control-block-size when combined with line-height + border.
+         padding-block 0.375rem × 2 + border 1px × 2 + line-height 1.5 × 1rem =
+         12px + 2px + 24px = 38px < 40px (min-block-size). */
+      padding-block: var(--pl-space-1);
+      padding-inline: var(--pl-control-padding-inline);
+      border: var(--pl-control-border-width) solid var(--c-field-border);
+      border-radius: var(--pl-control-radius);
+      background: var(--c-field-bg);
+      color: var(--c-field-fg);
+      transition:
+        border-color var(--pl-duration-1) var(--pl-ease-standard),
+        box-shadow var(--pl-duration-1) var(--pl-ease-standard);
+    }
+
+    select.c-field__control {
+      padding-inline-end: var(--pl-space-8);
+      background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='currentColor' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpolyline points='6 9 12 15 18 9'%3E%3C/polyline%3E%3C/svg%3E");
+      background-repeat: no-repeat;
+      background-position: right var(--pl-space-3) center;
+      background-size: 1rem;
+    }
+
+    .c-field__control::placeholder {
+      color: var(--pl-color-text-muted);
+    }
+
+    .c-field__hint {
+      color: var(--pl-color-text-muted);
+      font-size: var(--pl-text-sm);
+    }
+  }
+
+  /* State rules OUTSIDE @scope. Live-state pseudos (:focus-visible,
+     :user-invalid) inside @scope (.c-field) do not reliably apply to the
+     focused control  -  @scope evaluates subtree membership but state pseudos
+     need direct element matching. Keeping them in the same layer, just
+     unscoped, with a :where() prefix for low specificity. */
+
+  /* Focus indicator: a single crisp 2px ring in the focus color, plus a
+     genuinely BLURRED outer glow. The border is NOT recolored  -  recoloring it
+     produced a “double blue stroke” (solid recolored border + a translucent
+     ring stacked beside it). The ring is the focus indicator; the border
+     stays as the neutral field edge. (The previous `0 0 0 4px` had no blur,
+     so it was a hard translucent ring, not the intended glow.) */
+  :where(.c-field) .c-field__control: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));
+  }
+
+  /* Invalid: same single-ring + glow treatment, in danger. The hint still
+     flips to danger-text via :has() on the wrapper (below). */
+  :where(.c-field) .c-field__control: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));
+  }
+
+  :where(.c-field):has(.c-field__control:user-invalid) .c-field__hint {
+    color: var(--pl-color-danger-text);
+  }
+
+  :where(.c-field):has(.c-field__control:disabled) {
+    opacity: var(--pl-opacity-disabled);
+  }
+
+  :where(.c-field):has(.c-field__control:disabled) .c-field__control {
+    cursor: not-allowed;
+  }
+
+  @media (forced-colors: active) {
+    :where(.c-field) .c-field__control {
+      border-color: ButtonBorder;
+    }
+  }
+}

package/src/06-components/file-upload.css

@@ -0,0 +1,104 @@
+/*
+ * Porchlight  -  file upload component
+ * ===========================================================================
+ * A drag-and-drop file upload zone. The native <input type="file"> is
+ * visually hidden; the zone is the click target. Uses :has() for the
+ * drag-over state (set [data-dragging] via JS) and disabled state.
+ *
+ * Structure:
+ *   <label class="c-file-upload">
+ *     <input type="file" class="c-file-upload__input" multiple />
+ *     <span class="c-file-upload__zone">
+ *       <svg class="c-file-upload__icon">...</svg>
+ *       <span class="c-file-upload__text">
+ *         <strong>Drag files here</strong> or click to browse
+ *       </span>
+ *     </span>
+ *   </label>
+ */
+@layer porchlight.components {
+  @scope (.c-file-upload) {
+    :scope {
+      --c-upload-pad: var(--pl-space-6);
+      --c-upload-gap: var(--pl-space-3);
+      --c-upload-border: 2px dashed var(--pl-color-border);
+      --c-upload-radius: var(--pl-radius-lg);
+
+      display: block;
+      cursor: pointer;
+    }
+
+    /* Visually hide the native input. */
+    .c-file-upload__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;
+    }
+
+    .c-file-upload__zone {
+      display: flex;
+      flex-direction: column;
+      align-items: center;
+      justify-content: center;
+      gap: var(--c-upload-gap);
+      padding: var(--c-upload-pad);
+      border: var(--c-upload-border);
+      border-radius: var(--c-upload-radius);
+      background: var(--pl-color-surface-2);
+      text-align: center;
+      transition:
+        border-color var(--pl-duration-2) var(--pl-ease-standard),
+        background-color var(--pl-duration-2) var(--pl-ease-standard);
+    }
+
+    /* Hover/drag-over: accent border + subtle tint. */
+    :scope:hover .c-file-upload__zone,
+    :scope[data-dragging] .c-file-upload__zone {
+      border-color: var(--pl-color-accent);
+      background: color-mix(in oklab, var(--pl-color-accent), transparent 92%);
+    }
+
+    /* Focus ring (when the hidden input is focused). */
+    :scope:has(input:focus-visible) .c-file-upload__zone {
+      outline: var(--pl-focus-size) solid var(--pl-focus-color);
+      outline-offset: var(--pl-focus-offset);
+    }
+
+    /* Disabled. */
+    :scope:has(input:disabled) {
+      cursor: not-allowed;
+
+      & .c-file-upload__zone {
+        opacity: var(--pl-opacity-disabled);
+      }
+    }
+
+    .c-file-upload__icon {
+      inline-size: 2rem;
+      block-size: 2rem;
+      color: var(--pl-color-text-muted);
+    }
+
+    .c-file-upload__text {
+      font-size: var(--pl-text-sm);
+      color: var(--pl-color-text-muted);
+    }
+
+    .c-file-upload__text strong {
+      color: var(--pl-color-text);
+    }
+  }
+
+  @media (forced-colors: active) {
+    :where(.c-file-upload__zone) {
+      border-color: ButtonBorder;
+      background: Canvas;
+    }
+  }
+}

package/src/06-components/nav.css

@@ -0,0 +1,185 @@
+/*
+ * Porchlight  -  nav (sidebar navigation) component
+ * ===========================================================================
+ * A vertical navigation list for sidebars. Icon + label items with active
+ * state via aria-current="page". Collapsible sub-sections via native
+ * <details> for zero-JS expand/collapse. Designed to compose with
+ * .l-app-shell__sidebar.
+ *
+ * Structure:
+ *   <nav class="c-nav" aria-label="Main">
+ *     <a class="c-nav__item" aria-current="page">
+ *       <svg class="c-nav__icon">...</svg>
+ *       <span class="c-nav__label">Dashboard</span>
+ *     </a>
+ *     <details class="c-nav__section">
+ *       <summary class="c-nav__section-trigger">
+ *         <svg class="c-nav__icon">...</svg>
+ *         <span>Projects</span>
+ *         <svg class="c-nav__chevron">...</svg>
+ *       </summary>
+ *       <a class="c-nav__item c-nav__item--child">Active</a>
+ *       <a class="c-nav__item c-nav__item--child">Archived</a>
+ *     </details>
+ *   </nav>
+ *
+ * The icon rail variant: when the sidebar is collapsed (icon-only mode),
+ * [data-variant="icons"] hides labels and centers icons.
+ */
+@layer porchlight.components {
+  @scope (.c-nav) {
+    :scope {
+      --c-nav-gap: var(--pl-space-1);
+      --c-nav-pad: var(--pl-space-2);
+
+      display: flex;
+      flex-direction: column;
+      gap: var(--c-nav-gap);
+      padding: var(--c-nav-pad);
+    }
+
+    .c-nav__item {
+      display: flex;
+      align-items: center;
+      gap: var(--pl-space-3);
+      padding: var(--pl-space-2) var(--pl-space-3);
+      border-radius: var(--pl-radius-md);
+      color: var(--pl-color-text-muted);
+      font-size: var(--pl-text-sm);
+      font-weight: var(--pl-font-weight-medium);
+      text-decoration: none;
+      cursor: pointer;
+      transition:
+        background-color var(--pl-duration-1) var(--pl-ease-standard),
+        color var(--pl-duration-1) var(--pl-ease-standard),
+        box-shadow var(--pl-duration-1) var(--pl-ease-standard);
+    }
+
+    .c-nav__item:hover {
+      background: var(--pl-color-surface-2);
+      color: var(--pl-color-text);
+    }
+
+    .c-nav__item:focus-visible {
+      outline: var(--pl-focus-size) solid var(--pl-focus-color);
+      outline-offset: var(--pl-focus-offset);
+    }
+
+    /* Active item  -  left-bar accent pattern: a 3px inset shadow on the
+       leading edge reads as a rail marker, strongly signalling "you are here".
+       Asymmetric border-radius (0 on start side) anchors the bar to the edge. */
+    .c-nav__item[aria-current="page"],
+    .c-nav__item[aria-current="true"] {
+      background: color-mix(in oklab, var(--pl-color-accent), transparent 90%);
+      color: var(--pl-color-accent);
+      font-weight: var(--pl-font-weight-semibold);
+      border-radius: 0 var(--pl-radius-md) var(--pl-radius-md) 0;
+      box-shadow: inset var(--pl-accent-bar-width) 0 0 var(--pl-color-accent);
+    }
+
+    /* Nested item (inside a section). */
+    .c-nav__item--child {
+      padding-inline-start: calc(
+        var(--pl-space-3) + 1.25rem + var(--pl-space-3)
+      );
+      font-size: var(--pl-text-sm);
+    }
+
+    .c-nav__icon {
+      inline-size: 1.25rem;
+      block-size: 1.25rem;
+      flex-shrink: 0;
+      color: inherit;
+    }
+
+    .c-nav__label {
+      flex: 1;
+      min-inline-size: 0;
+      overflow: hidden;
+      text-overflow: ellipsis;
+      white-space: nowrap;
+    }
+
+    /* Badge in a nav item (e.g. unread count). */
+    .c-nav__badge {
+      margin-inline-start: auto;
+    }
+
+    /* Collapsible section. */
+    .c-nav__section {
+      display: flex;
+      flex-direction: column;
+      gap: var(--pl-space-1);
+    }
+
+    .c-nav__section-trigger {
+      display: flex;
+      align-items: center;
+      gap: var(--pl-space-3);
+      padding: var(--pl-space-2) var(--pl-space-3);
+      border-radius: var(--pl-radius-md);
+      color: var(--pl-color-text-muted);
+      font-size: var(--pl-text-sm);
+      font-weight: var(--pl-font-weight-medium);
+      cursor: pointer;
+      user-select: none;
+      list-style: none;
+      transition: all var(--pl-duration-1) var(--pl-ease-standard);
+
+      &::-webkit-details-marker {
+        display: none;
+      }
+
+      &::marker {
+        content: "";
+      }
+    }
+
+    .c-nav__section-trigger:hover {
+      background: var(--pl-color-surface-2);
+      color: var(--pl-color-text);
+    }
+
+    .c-nav__section-trigger:focus-visible {
+      outline: var(--pl-focus-size) solid var(--pl-focus-color);
+      outline-offset: var(--pl-focus-offset);
+    }
+
+    .c-nav__chevron {
+      margin-inline-start: auto;
+      inline-size: 1rem;
+      block-size: 1rem;
+      flex-shrink: 0;
+      color: var(--pl-color-text-muted);
+      transition: rotate var(--pl-duration-2) var(--pl-ease-standard);
+    }
+
+    .c-nav__section[open] .c-nav__chevron {
+      rotate: 90deg;
+    }
+
+    /* Icons-only variant (collapsed sidebar). */
+    :scope[data-variant="icons"] .c-nav__label,
+    :scope[data-variant="icons"] .c-nav__chevron,
+    :scope[data-variant="icons"] .c-nav__badge {
+      display: none;
+    }
+
+    :scope[data-variant="icons"] .c-nav__item,
+    :scope[data-variant="icons"] .c-nav__section-trigger {
+      justify-content: center;
+      padding: var(--pl-space-2);
+    }
+  }
+
+  @media (forced-colors: active) {
+    :where(.c-nav__item[aria-current="page"]) {
+      background: Highlight;
+      color: HighlightText;
+    }
+
+    :where(.c-nav__item:focus-visible) {
+      outline-color: Highlight;
+    }
+  }
+}