@netlify/spark-ui 1.26.0-alpha.7 → 1.26.0-alpha.8

package/dist/components/FilterableGrid/filter-types.d.ts

@@ -0,0 +1,40 @@
+export interface FilterOption {
+    value: string;
+    label: string;
+}
+export interface FilterCategory {
+    key: string;
+    label: string;
+    legend?: string;
+    control?: 'checkbox' | 'radio';
+    /** Radio-only: prepend a checked `value=""` reset row. */
+    anyOption?: {
+        label: string;
+    };
+    matchMode?: 'any' | 'all';
+    options: FilterOption[];
+}
+export interface FilterableGridProps {
+    filters: FilterCategory[];
+    results: {
+        singular: string;
+        plural: string;
+    };
+    /** Server-rendered initial count, shown before any client JS runs. */
+    totalCount: number;
+    /** Global match mode; per-category `matchMode` overrides it for that category. */
+    matchMode: 'any' | 'all';
+    id?: string;
+}
+/**
+ * Builds the `data-filter-{key}` attributes a slotted grid item needs so
+ * `<filter-container>` can match it against the active facets. Spread the
+ * result onto whatever bespoke element you render inside <FilterableGrid>.
+ *
+ * @example
+ * <article {...getFilterAttrs({ topic: ['react', 'astro'], level: 'beginner' })}>
+ *   ...
+ * </article>
+ * // -> data-filter-topic="react,astro" data-filter-level="beginner"
+ */
+export declare function getFilterAttrs(values: Record<string, string | string[]>, delimiter?: string): Record<`data-filter-${string}`, string>;

package/dist/components/FilterableGrid/index.d.ts

@@ -0,0 +1,2 @@
+export { default as FilterableGrid } from './FilterableGrid.astro';
+export * from './filter-types';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@netlify/spark-ui",
   "description": "Assets, design tokens, components, and utilities",
-  "version": "1.26.0-alpha.7",
+  "version": "1.26.0-alpha.8",
   "type": "module",
   "main": "dist/components/preact/index.js",
   "types": "dist/components/preact/index.d.ts",
@@ -31,6 +31,7 @@
     "./styles/*.css": "./packages/styles/*.css",
     "./assets/*": "./packages/assets/*",
     "./components": "./packages/components/index.ts",
+    "./components/FilterableGrid": "./packages/components/FilterableGrid/index.ts",
     "./components/*": "./packages/components/*",
     "./utils": "./packages/utils/index.ts",
     "./analytics": "./packages/analytics/index.ts"
@@ -39,6 +40,8 @@
     "@astro-community/astro-embed-youtube": "^0.5.10",
     "@kapaai/react-sdk": "^0.9.0",
     "@shikijs/transformers": "^3.3.0",
+    "@zachleat/details-utils": "^2.0.2",
+    "@zachleat/filter-container": "^4.0.0",
     "fflate": "^0.8.2",
     "marked": "^15.0.11",
     "rusha": "^0.8.14"

package/packages/components/Button.astro

@@ -8,6 +8,7 @@ interface Props {
   target?: string;
   variant?: BUTTON_VARIANTS;
   href?: string;
+  type?: 'button' | 'submit' | 'reset';
 }
 
 const {
@@ -16,6 +17,7 @@ const {
   variant = 'primary',
   href,
   target = !href?.includes(Astro.url.origin) ? '_blank' : undefined,
+  type,
   ...rest
 } = Astro.props;
 
@@ -28,6 +30,7 @@ const Element = href ? 'a' : 'button';
   data-button-variant={variant}
   {href}
   {target}
+  type={!href ? type : undefined}
   {...rest}
 >
   <slot />

package/packages/components/FilterableGrid/FilterableGrid.astro

@@ -0,0 +1,403 @@
+---
+import type { FilterableGridProps } from './filter-types';
+import Button from '../Button.astro';
+
+const { filters, results, totalCount, matchMode, id } = Astro.props as FilterableGridProps;
+
+const filterModeAttrs = Object.fromEntries(
+  filters
+    .filter(category => category.matchMode)
+    .map(category => [`filter-mode-${category.key}`, category.matchMode])
+);
+
+const initialResultsLabel = `${totalCount} ${totalCount === 1 ? results.singular : results.plural}`;
+---
+
+<div id={id} data-filter-root>
+  {
+    filters.length > 0 && (
+      <filter-container oninit filter-mode={matchMode} {...filterModeAttrs}>
+        <form class="n-filter-form" data-filter-form>
+          <details-utils
+            class="n-filter-dropdowns"
+            force-close="(min-width: 37.5em)"
+            force-restore
+            close-click-outside="(min-width: 37.5em)"
+            animate
+          >
+            {filters.map(category => (
+              <details class="n-filter-facet">
+                <summary>
+                  <span class="n-filter-label">
+                    {category.label}
+                    <span class="n-filter-count" data-filter-count-badge data-filter-category={category.key}>
+                      0
+                    </span>
+                  </span>
+                  <svg
+                    class="n-filter-chevron-icon"
+                    viewBox="0 0 512 512"
+                    fill="none"
+                    role="presentation"
+                  >
+                    <path
+                      d="M233.4 406.6c12.5 12.5 32.8 12.5 45.3 0l192-192c12.5-12.5 12.5-32.8 0-45.3s-32.8-12.5-45.3 0L256 338.7 86.6 169.4c-12.5-12.5-32.8-12.5-45.3 0s-12.5 32.8 0 45.3l192 192z"
+                      fill="currentcolor"
+                    />
+                  </svg>
+                </summary>
+                <fieldset class="n-filter-menu">
+                  <legend class="n-filter-legend">{category.legend ?? `${category.label}:`}</legend>
+                  {category.control === 'radio' && category.anyOption && (
+                    <label>
+                      <input
+                        type="radio"
+                        name={category.key}
+                        value=""
+                        data-filter-key={category.key}
+                        checked
+                      />
+                      {category.anyOption.label}
+                    </label>
+                  )}
+                  {category.options.map(option => (
+                    <label>
+                      <input
+                        type={category.control === 'radio' ? 'radio' : 'checkbox'}
+                        name={category.key}
+                        value={option.value}
+                        data-filter-key={category.key}
+                      />
+                      {option.label}
+                    </label>
+                  ))}
+                </fieldset>
+              </details>
+            ))}
+          </details-utils>
+        </form>
+
+        <div class="n-filter-meta">
+          <p
+            class="n-filter-results"
+            data-filter-results={`${results.singular}/${results.plural}`}
+            aria-live="polite"
+          >
+            {initialResultsLabel}
+          </p>
+          <ul class="n-filter-tags" role="list" data-filter-tags>
+            {filters.flatMap(category =>
+              category.options.map(option => (
+                <li
+                  class="n-filter-tag"
+                  data-tag-key={category.key}
+                  data-tag-value={option.value}
+                  hidden
+                >
+                  <Button
+                    type="button"
+                    variant="outline"
+                    data-tag-key={category.key}
+                    data-tag-value={option.value}
+                  >
+                    {option.label}
+                    <svg class="n-close-icon" viewBox="0 0 512 512" fill="none" role="presentation">
+                      <path
+                        d="M342.6 150.6c12.5-12.5 12.5-32.8 0-45.3s-32.8-12.5-45.3 0L192 210.7 86.6 105.4c-12.5-12.5-32.8-12.5-45.3 0s-12.5 32.8 0 45.3L146.7 256 41.4 361.4c-12.5 12.5-12.5 32.8 0 45.3s32.8 12.5 45.3 0L192 301.3l105.4 105.3c12.5 12.5 32.8 12.5 45.3 0s12.5-32.8 0-45.3L237.3 256z"
+                        fill="currentcolor"
+                      />
+                    </svg>
+                  </Button>
+                </li>
+              ))
+            )}
+          </ul>
+        </div>
+
+        <slot />
+      </filter-container>
+    )
+  }
+  {filters.length === 0 && <slot />}
+</div>
+
+<script src="@zachleat/filter-container/filter-container.js"></script>
+<script src="@zachleat/details-utils/details-utils.js"></script>
+<script>
+  function initFilterableGrid(root: HTMLElement): void {
+    const form = root.querySelector<HTMLFormElement>('[data-filter-form]');
+    if (!form) return;
+
+    const tagsList = root.querySelector<HTMLUListElement>('[data-filter-tags]');
+
+    const updateCount = (key: string) => {
+      const count = Array.from(
+        form.querySelectorAll<HTMLInputElement>(`[data-filter-key="${CSS.escape(key)}"]:checked`)
+      ).filter(entry => !!entry.value).length;
+      const counter = root.querySelector<HTMLElement>(
+        `[data-filter-count-badge][data-filter-category="${CSS.escape(key)}"]`
+      );
+      if (counter) {
+        counter.textContent = String(count);
+        counter.classList.toggle('is-visible', count > 0);
+      }
+    };
+
+    const showChip = (chipLi: HTMLLIElement) => {
+      if (!tagsList) return;
+      chipLi.hidden = false;
+      tagsList.appendChild(chipLi);
+    };
+
+    const hideChip = (chipLi: HTMLLIElement) => {
+      chipLi.hidden = true;
+    };
+
+    const findChip = (key: string, value: string): HTMLLIElement | null =>
+      tagsList?.querySelector<HTMLLIElement>(
+        `li[data-tag-key="${CSS.escape(key)}"][data-tag-value="${CSS.escape(value)}"]`
+      ) ?? null;
+
+    const onCheckboxInput = (key: string, value: string, checked: boolean) => {
+      const chip = findChip(key, value);
+      if (!chip) return;
+      if (checked) showChip(chip);
+      else hideChip(chip);
+    };
+
+    const onRadioInput = (key: string, value: string) => {
+      if (!tagsList) return;
+      tagsList
+        .querySelectorAll<HTMLLIElement>(`li[data-tag-key="${CSS.escape(key)}"]`)
+        .forEach(chip => {
+          if (value && chip.dataset.tagValue === value) showChip(chip);
+          else hideChip(chip);
+        });
+    };
+
+    const onTagInput = (input: HTMLInputElement) => {
+      if (!tagsList) return;
+      const key = input.dataset.filterKey;
+      if (!key) return;
+      if (input.type === 'radio') onRadioInput(key, input.value);
+      else onCheckboxInput(key, input.value, input.checked);
+    };
+
+    form.addEventListener('input', event => {
+      if (!(event.target instanceof HTMLInputElement)) return;
+      const key = event.target.dataset.filterKey;
+      if (key) updateCount(key);
+      if (tagsList) onTagInput(event.target);
+    });
+
+    tagsList?.addEventListener('click', event => {
+      const button = (event.target as HTMLElement).closest('button');
+      if (!button || !tagsList.contains(button)) return;
+      const key = button.dataset.tagKey;
+      const value = button.dataset.tagValue;
+      if (!key || value === undefined) return;
+      const input = form.querySelector<HTMLInputElement>(
+        `input[name="${CSS.escape(key)}"][value="${CSS.escape(value)}"]`
+      );
+      if (!input) return;
+      if (input.type === 'radio') {
+        const resetRadio = form.querySelector<HTMLInputElement>(
+          `input[type="radio"][name="${CSS.escape(key)}"][value=""]`
+        );
+        resetRadio?.dispatchEvent(
+          new MouseEvent('click', { view: window, bubbles: true, cancelable: true })
+        );
+      } else {
+        input.dispatchEvent(
+          new MouseEvent('click', { view: window, bubbles: true, cancelable: true })
+        );
+      }
+    });
+
+    // Seed counts/chips from state restored by filter-container's `oninit` (e.g. from URL params).
+    window.addEventListener('load', () => {
+      const checked = form.querySelectorAll<HTMLInputElement>('[data-filter-key]:checked');
+      checked.forEach(input => {
+        const key = input.dataset.filterKey;
+        if (key) updateCount(key);
+        if (tagsList) onTagInput(input);
+      });
+    });
+  }
+
+  const filterRoot = document.querySelector<HTMLElement>('[data-filter-root]');
+  if (filterRoot) initFilterableGrid(filterRoot);
+</script>
+
+<style>
+  .n-filter-form {
+    display: flex;
+    justify-content: center;
+    margin-block-end: var(--ntl-space-s);
+  }
+
+  .n-filter-dropdowns {
+    display: flex;
+    flex-wrap: wrap;
+    justify-content: center;
+    width: 100%;
+    border-radius: var(--ntl-radius-m);
+  }
+
+  @media (min-width: 37.5em) {
+    .n-filter-dropdowns {
+      display: inline-flex;
+      width: auto;
+      gap: var(--ntl-space-s);
+      padding: var(--ntl-space-s);
+      background-color: var(--ntl-color-bg-2);
+    }
+  }
+
+  .n-filter-facet {
+    width: 100%;
+    border-top: 1px solid var(--ntl-color-border-strong);
+  }
+
+  .n-filter-facet:last-child {
+    border-bottom: 1px solid var(--ntl-color-border-strong);
+  }
+
+  @media (min-width: 37.5em) {
+    .n-filter-facet,
+    .n-filter-facet:last-child {
+      width: auto;
+      border: none;
+    }
+  }
+
+  .n-filter-facet > summary {
+    position: relative;
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: var(--ntl-space-2xs);
+    padding-block: var(--ntl-space-2xs);
+    color: var(--ntl-heading-text-color);
+    cursor: pointer;
+    list-style: none;
+  }
+
+  .n-filter-facet > summary::-webkit-details-marker {
+    display: none;
+  }
+
+  @media (min-width: 37.5em) {
+    .n-filter-facet > summary {
+      padding: var(--ntl-space-2xs) var(--ntl-space-s);
+      border: 1px solid var(--ntl-color-border-strong);
+      border-radius: var(--ntl-radius-m);
+      background-color: var(--ntl-color-bg);
+    }
+
+    .n-filter-facet[open] > summary {
+      border-color: var(--ntl-blue-700);
+    }
+  }
+
+  .n-filter-label {
+    display: flex;
+    align-items: center;
+    gap: var(--ntl-space-3xs);
+  }
+
+  .n-filter-chevron-icon {
+    width: 0.7em;
+  }
+
+  .n-filter-count {
+    display: none;
+    align-items: center;
+    justify-content: center;
+    width: 1.5em;
+    height: 1.5em;
+    border-radius: 50%;
+    background: var(--ntl-blue-700);
+    color: var(--ntl-neutral-000);
+    font-size: 0.75em;
+  }
+
+  .n-filter-facet[open] .n-filter-count,
+  .n-filter-facet:not([open]) .n-filter-count.is-visible {
+    display: inline-flex;
+  }
+
+  @media (min-width: 37.5em) {
+    .n-filter-count {
+      position: absolute;
+      top: -0.5em;
+      right: -0.75em;
+    }
+  }
+
+  .n-filter-menu {
+    display: flex;
+    flex-direction: column;
+    padding-block: var(--ntl-space-2xs) var(--ntl-space-s);
+    border: none;
+  }
+
+  .n-filter-menu label {
+    display: flex;
+    align-items: center;
+    white-space: nowrap;
+  }
+
+  .n-filter-menu label:not(:last-child) {
+    margin-block-end: var(--ntl-space-2xs);
+  }
+
+  .n-filter-menu input[type='checkbox'],
+  .n-filter-menu input[type='radio'] {
+    margin-inline-end: var(--ntl-space-2xs);
+    accent-color: var(--ntl-blue-700);
+  }
+
+  .n-filter-legend {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    padding: 0;
+    margin: -1px;
+    overflow: hidden;
+    clip: rect(0, 0, 0, 0);
+    white-space: nowrap;
+    border: 0;
+  }
+
+  @media (min-width: 37.5em) {
+    .n-filter-menu {
+      position: absolute;
+      z-index: 1;
+      padding: var(--ntl-space-s);
+      border-radius: var(--ntl-radius-m);
+      background-color: var(--ntl-color-bg);
+      box-shadow: var(--ntl-shadow-deep, 0 0.5rem 1.5rem rgba(0, 0, 0, 0.2));
+    }
+  }
+
+  .n-filter-meta {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    gap: var(--ntl-space-s);
+    margin-block-end: var(--ntl-space-l);
+  }
+
+  .n-filter-results {
+    color: var(--ntl-color-text-weak);
+  }
+
+  .n-filter-tags {
+    display: flex;
+    flex-wrap: wrap;
+    justify-content: center;
+    gap: var(--ntl-space-s);
+    list-style: none;
+  }
+</style>

package/packages/components/FilterableGrid/filter-types.ts

@@ -0,0 +1,48 @@
+export interface FilterOption {
+  value: string;
+  label: string;
+}
+
+export interface FilterCategory {
+  key: string;
+  label: string;
+  legend?: string;
+  control?: 'checkbox' | 'radio';
+  /** Radio-only: prepend a checked `value=""` reset row. */
+  anyOption?: { label: string };
+  matchMode?: 'any' | 'all';
+  options: FilterOption[];
+}
+
+export interface FilterableGridProps {
+  filters: FilterCategory[];
+  results: { singular: string; plural: string };
+  /** Server-rendered initial count, shown before any client JS runs. */
+  totalCount: number;
+  /** Global match mode; per-category `matchMode` overrides it for that category. */
+  matchMode: 'any' | 'all';
+  id?: string;
+}
+
+/**
+ * Builds the `data-filter-{key}` attributes a slotted grid item needs so
+ * `<filter-container>` can match it against the active facets. Spread the
+ * result onto whatever bespoke element you render inside <FilterableGrid>.
+ *
+ * @example
+ * <article {...getFilterAttrs({ topic: ['react', 'astro'], level: 'beginner' })}>
+ *   ...
+ * </article>
+ * // -> data-filter-topic="react,astro" data-filter-level="beginner"
+ */
+export function getFilterAttrs(
+  values: Record<string, string | string[]>,
+  delimiter = ','
+): Record<`data-filter-${string}`, string> {
+  return Object.fromEntries(
+    Object.entries(values).map(([key, value]) => [
+      `data-filter-${key}`,
+      Array.isArray(value) ? value.join(delimiter) : value,
+    ])
+  ) as Record<`data-filter-${string}`, string>;
+}

package/packages/components/FilterableGrid/index.ts

@@ -0,0 +1,2 @@
+export { default as FilterableGrid } from './FilterableGrid.astro';
+export * from './filter-types';