@profpowell/vb-design-system 0.1.0

package/src/web-components/gradient-builder/logic.js

@@ -0,0 +1,261 @@
+/**
+ * gradient-builder — Interactive CSS gradient tool
+ *
+ * Visual gradient preview with color stop management, angle/type controls,
+ * color space selection, and CSS export. Companion to palette-generator.
+ *
+ * @attr {string}  colors        - Comma-separated initial stop colors
+ * @attr {string}  type          - "linear" (default) or "radial"
+ * @attr {number}  angle         - Gradient angle in degrees (default: 90)
+ * @attr {string}  interpolation - Color space: "oklab" (default), "oklch", "srgb"
+ * @attr {boolean} show-export   - Show Copy CSS toolbar
+ * @attr {boolean} show-controls - Show type/angle/space controls (default: true)
+ *
+ * @fires gradient-builder:change - { css, stops, type, angle, interpolation }
+ *
+ * @example
+ * <gradient-builder colors="#6366f1,#ec4899" show-export></gradient-builder>
+ */
+
+import { registerComponent } from '../../lib/bundle-registry.js';
+import { VBElement } from '../../lib/vb-element.js';
+import { copyText } from '../../utils/copy-init.js';
+import { buildGradientCSS, parseColorStops, defaultStops } from './_gradient-utils.js';
+
+class GradientBuilder extends VBElement {
+  static observedAttributes = ['colors', 'type', 'angle', 'interpolation', 'show-export', 'show-controls'];
+
+  /** @type {import('./_gradient-utils.js').GradientStop[]} */
+  #stops = [];
+  #type = 'linear';
+  #angle = 90;
+  #interpolation = 'oklab';
+
+  setup() {
+    this.#stops = parseColorStops(this.getAttribute('colors') ?? '');
+    this.#type = this.getAttribute('type') || 'linear';
+    this.#angle = Number(this.getAttribute('angle')) || 90;
+    this.#interpolation = this.getAttribute('interpolation') || 'oklab';
+    this.#render();
+    return true;
+  }
+
+  attributeChangedCallback(name, oldVal, newVal) {
+    if (oldVal === newVal || !this.isConnected) return;
+    if (name === 'colors') this.#stops = parseColorStops(newVal);
+    if (name === 'type') this.#type = newVal || 'linear';
+    if (name === 'angle') this.#angle = Number(newVal) || 90;
+    if (name === 'interpolation') this.#interpolation = newVal || 'oklab';
+    this.#render();
+  }
+
+  get css() {
+    return buildGradientCSS(this.#stops, {
+      type: this.#type,
+      angle: this.#angle,
+      interpolation: this.#interpolation,
+    });
+  }
+
+  #render() {
+    const showExport = this.hasAttribute('show-export');
+    const showControls = this.getAttribute('show-controls') !== 'false';
+    const css = this.css;
+
+    const gap = 'var(--size-m, 1rem)';
+    const smGap = 'var(--size-s, 0.75rem)';
+    const xsGap = 'var(--size-xs, 0.5rem)';
+    const radius = 'var(--radius-m, 0.5rem)';
+    const border = 'var(--color-border, #ddd)';
+    const surface = 'var(--color-surface, #fff)';
+    const muted = 'var(--color-text-muted, #666)';
+    const mono = 'var(--font-mono, monospace)';
+    const smFont = 'var(--font-size-sm, 0.875rem)';
+    const xsFont = 'var(--font-size-xs, 0.75rem)';
+
+    // Preview strip
+    const preview = `<div class="gb-preview" style="height:4rem;border-radius:${radius};background:${css};border:1px solid ${border}"></div>`;
+
+    // Controls — Row 1: Type + Angle, Row 2: Color Space
+    const selectStyle = `font:inherit;font-size:${smFont};padding:0.25rem 0.5rem;border:1px solid ${border};border-radius:4px;background:${surface}`;
+    let controls = '';
+    if (showControls) {
+      controls = `<div style="display:flex;flex-direction:column;gap:${smGap};font-size:${smFont}">
+        <div style="display:flex;flex-wrap:wrap;gap:${gap};align-items:center">
+          <label style="display:flex;align-items:center;gap:${xsGap}">
+            Type
+            <select class="gb-type" style="${selectStyle}">
+              <option value="linear"${this.#type === 'linear' ? ' selected' : ''}>Linear</option>
+              <option value="radial"${this.#type === 'radial' ? ' selected' : ''}>Radial</option>
+            </select>
+          </label>
+          <label style="display:flex;align-items:center;gap:${xsGap}${this.#type === 'radial' ? ';opacity:0.4;pointer-events:none' : ''}">
+            Angle
+            <input type="range" class="gb-angle" min="0" max="360" value="${this.#angle}" style="width:8rem;accent-color:var(--color-interactive,oklch(55% .2 260))">
+            <span class="gb-angle-value" style="min-width:2.5em;font-family:${mono};font-size:${xsFont}">${this.#angle}°</span>
+          </label>
+        </div>
+        <label style="display:inline-flex;align-items:center;gap:${xsGap}">
+          Color Space
+          <select class="gb-space" style="${selectStyle}">
+            <option value="oklab"${this.#interpolation === 'oklab' ? ' selected' : ''}>oklab</option>
+            <option value="oklch"${this.#interpolation === 'oklch' ? ' selected' : ''}>oklch</option>
+            <option value="srgb"${this.#interpolation === 'srgb' ? ' selected' : ''}>sRGB</option>
+          </select>
+        </label>
+      </div>`;
+    }
+
+    // Sort stops by position for display
+    const sorted = [...this.#stops].map((s, i) => ({ ...s, origIndex: i })).sort((a, b) => a.position - b.position);
+
+    // Stop editors — horizontal wrapping row
+    const stopRows = sorted.map((stop) => {
+      const i = stop.origIndex;
+      return `<div style="display:flex;align-items:center;gap:0.375rem" data-stop="${i}">
+        <input type="color" value="${stop.color}" class="gb-stop-color" data-i="${i}"
+          style="width:1.75rem;height:1.75rem;padding:0;border:1px solid ${border};border-radius:4px;cursor:pointer;flex-shrink:0">
+        <input type="range" min="0" max="100" value="${stop.position}" class="gb-stop-pos-range" data-i="${i}"
+          style="flex:1;min-width:3rem;max-width:8rem;accent-color:${stop.color}">
+        <span style="font-family:${mono};font-size:${xsFont};min-width:2.5em;text-align:right" class="gb-stop-pos-label" data-i="${i}">${stop.position}%</span>
+        ${this.#stops.length > 2 ? `<button type="button" class="gb-remove" data-i="${i}"
+          style="all:unset;cursor:pointer;font-size:1rem;color:${muted};padding:0 0.25rem" title="Remove stop">&times;</button>` : ''}
+      </div>`;
+    }).join('');
+
+    const addBtn = `<button type="button" class="gb-add"
+      style="all:unset;cursor:pointer;font-size:${smFont};color:var(--color-interactive,oklch(55% .2 260));font-weight:600">+ Add Stop</button>`;
+
+
+    this.innerHTML = `
+      <div style="display:flex;flex-direction:column;gap:${gap}">
+        ${preview}
+        ${controls}
+        <div style="display:flex;flex-direction:column;gap:${xsGap}">
+          <span style="font-size:${xsFont};font-weight:600;color:${muted};text-transform:uppercase;letter-spacing:0.05em">Color Stops</span>
+          ${stopRows}
+          ${addBtn}
+        </div>
+        <div style="display:flex;flex-direction:column;gap:${xsGap}">
+          <span style="font-size:${xsFont};font-weight:600;color:${muted};text-transform:uppercase;letter-spacing:0.05em">Code</span>
+          <div style="display:flex;align-items:start;gap:${xsGap}">
+            <div style="flex:1;font-family:${mono};font-size:${xsFont};padding:${smGap};background:var(--color-surface-raised,#f5f5f5);border-radius:${radius};word-break:break-all;color:var(--color-text,#222)" class="gb-css-output">${css}</div>
+            ${showExport ? `<button type="button" class="gb-copy"
+              style="all:unset;cursor:pointer;font-size:${xsFont};padding:0.35rem 0.75rem;border:1px solid ${border};border-radius:4px;background:${surface};white-space:nowrap;flex-shrink:0">Copy CSS</button>` : ''}
+          </div>
+        </div>
+      </div>
+    `;
+
+    this.#wire();
+  }
+
+  #wire() {
+    // Type select
+    this.querySelector('.gb-type')?.addEventListener('change', (e) => {
+      const t = /** @type {HTMLSelectElement} */ (e.target);
+      this.#type = t.value;
+      this.#render();
+      this.#emit();
+    });
+
+    // Angle slider
+    const angleInput = this.querySelector('.gb-angle');
+    const angleValue = this.querySelector('.gb-angle-value');
+    angleInput?.addEventListener('input', (e) => {
+      const t = /** @type {HTMLInputElement} */ (e.target);
+      this.#angle = Number(t.value);
+      if (angleValue) angleValue.textContent = `${this.#angle}°`;
+      // Live update preview without full re-render
+      const preview = /** @type {HTMLElement | null} */ (this.querySelector('.gb-preview'));
+      if (preview) preview.style.background = this.css;
+      this.#emit();
+    });
+
+    // Interpolation select
+    this.querySelector('.gb-space')?.addEventListener('change', (e) => {
+      const t = /** @type {HTMLSelectElement} */ (e.target);
+      this.#interpolation = t.value;
+      this.#render();
+      this.#emit();
+    });
+
+    // Stop color inputs
+    this.querySelectorAll('.gb-stop-color').forEach((input) => {
+      input.addEventListener('input', (e) => {
+        const t = /** @type {HTMLInputElement} */ (e.target);
+        const i = Number(t.dataset.i);
+        this.#stops[i].color = t.value;
+        this.#updatePreview();
+        this.#emit();
+      });
+    });
+
+    // Stop position range sliders
+    this.querySelectorAll('.gb-stop-pos-range').forEach((input) => {
+      input.addEventListener('input', (e) => {
+        const t = /** @type {HTMLInputElement} */ (e.target);
+        const i = Number(t.dataset.i);
+        const val = Math.max(0, Math.min(100, Number(t.value) || 0));
+        this.#stops[i].position = val;
+        const label = this.querySelector(`.gb-stop-pos-label[data-i="${i}"]`);
+        if (label) label.textContent = `${val}%`;
+        this.#updatePreview();
+        this.#emit();
+      });
+    });
+
+    // Remove stop buttons
+    this.querySelectorAll('.gb-remove').forEach((btn) => {
+      btn.addEventListener('click', (e) => {
+        const t = /** @type {HTMLElement} */ (e.target);
+        const i = Number(t.dataset.i);
+        this.#stops.splice(i, 1);
+        this.#render();
+        this.#emit();
+      });
+    });
+
+    // Add stop button
+    this.querySelector('.gb-add')?.addEventListener('click', () => {
+      // Insert a new stop at the midpoint between the last two stops
+      const last = this.#stops[this.#stops.length - 1];
+      const prev = this.#stops[this.#stops.length - 2];
+      const pos = Math.round((prev.position + last.position) / 2);
+      this.#stops.splice(this.#stops.length - 1, 0, { color: '#888888', position: pos });
+      this.#render();
+      this.#emit();
+    });
+
+    // Copy CSS button
+    this.querySelector('.gb-copy')?.addEventListener('click', (e) => {
+      const btn = /** @type {HTMLElement | null} */ (e.target);
+      if (!btn) return;
+      copyText(this.css, { button: btn, announceMessage: 'Gradient CSS copied' });
+    });
+  }
+
+  #updatePreview() {
+    const css = this.css;
+    const preview = /** @type {HTMLElement | null} */ (this.querySelector('.gb-preview'));
+    if (preview) preview.style.background = css;
+    const output = this.querySelector('.gb-css-output');
+    if (output) output.textContent = css;
+  }
+
+  #emit() {
+    this.dispatchEvent(new CustomEvent('gradient-builder:change', {
+      bubbles: true,
+      detail: {
+        css: this.css,
+        stops: [...this.#stops],
+        type: this.#type,
+        angle: this.#angle,
+        interpolation: this.#interpolation,
+      },
+    }));
+  }
+}
+
+registerComponent('gradient-builder', GradientBuilder);
+export { GradientBuilder };

package/src/web-components/gradient-builder/static.html

@@ -0,0 +1,9 @@
+<!DOCTYPE html>
+<html lang="en">
+<head><meta charset="utf-8"><title>Gradient Builder (Static Fallback)</title></head>
+<body>
+  <noscript>
+    <p>gradient-builder is an authoring tool for composing CSS gradients with live preview and copy-to-clipboard. It requires JS; no static fallback is meaningful.</p>
+  </noscript>
+</body>
+</html>

package/src/web-components/gradient-builder/styles.css

@@ -0,0 +1,10 @@
+/* gradient-builder: Interactive CSS gradient tool */
+
+gradient-builder {
+  display: block;
+  max-inline-size: 32rem;
+}
+
+gradient-builder:not(:defined) {
+  display: none;
+}

package/src/web-components/icon-set/api.json

@@ -0,0 +1,39 @@
+{
+  "$schema": "../../../schemas/api.schema.json",
+  "element": "icon-set",
+  "type": "web-component",
+  "description": "Searchable grid of every icon in a set, with click-to-copy names.",
+  "htmlvalidate": {
+    "flow": true,
+    "permittedContent": [
+      "@flow"
+    ]
+  },
+  "attributes": [
+    {
+      "name": "set",
+      "kind": "host-api",
+      "purpose": "config",
+      "type": "string",
+      "description": "Icon set directory (default: \"lucide\")"
+    },
+    {
+      "name": "names",
+      "kind": "host-api",
+      "purpose": "config",
+      "type": "string",
+      "description": "Optional space/comma-separated list of icon names. Overrides the {iconBase}/{set}.json manifest fetch."
+    }
+  ],
+  "childAttributes": [
+    {
+      "name": "name",
+      "kind": "host-api",
+      "purpose": "config",
+      "type": "string",
+      "element": "icon-wc",
+      "description": "Icon filename (without .svg), passed through from each grid cell."
+    }
+  ],
+  "structure": []
+}

package/src/web-components/icon-set/logic.js

@@ -0,0 +1,133 @@
+/**
+ * icon-set: Searchable icon catalog/browser
+ *
+ * Renders a filterable grid of icons for a given icon set, with
+ * click-to-copy names. Each cell renders the icon with the `[data-icon]`
+ * primitive (a currentColor CSS mask), lazy-mounted so a full set does not
+ * fetch every SVG at once.
+ *
+ * By default it fetches {iconBase}/{set}.json — a manifest listing every
+ * icon name in the set. The `names` attribute bypasses that fetch entirely
+ * (space/comma-separated list), which is useful for tests, offline demos,
+ * or curated subsets where no manifest exists.
+ *
+ * @attr {string} set   - Icon set directory (default: "lucide")
+ * @attr {string} names - Optional space/comma-separated list of icon names.
+ *                        Overrides the {iconBase}/{set}.json manifest fetch.
+ *
+ * @example
+ * <icon-set names="star home search settings"></icon-set>
+ * <icon-set set="lucide"></icon-set>
+ */
+
+import { registerComponent } from '../../lib/bundle-registry.js';
+import { VBElement } from '../../lib/vb-element.js';
+
+const iconBase = () => document.documentElement.dataset.iconPath || '/cdn/icons';
+
+class IconSet extends VBElement {
+  static observedAttributes = ['set', 'names'];
+
+  /** @type {IntersectionObserver | null} Lazy-mounts [data-icon] icons as cells scroll in. */
+  #io = null;
+
+  setup() {
+    this.#render();
+    this.#load();
+  }
+
+  attributeChangedCallback() {
+    if (this.isConnected) {
+      this.#render();
+      this.#load();
+    }
+  }
+
+  disconnectedCallback() {
+    this.#io?.disconnect();
+    this.#io = null;
+    super.disconnectedCallback?.();
+  }
+
+  get set() {
+    return this.getAttribute('set') || 'lucide';
+  }
+
+  async #load() {
+    const attr = this.getAttribute('names');
+    let names = attr ? attr.split(/[\s,]+/).filter(Boolean) : null;
+    if (!names) {
+      try {
+        names = await (await fetch(`${iconBase()}/${this.set}.json`)).json();
+      } catch {
+        names = [];
+      }
+    }
+    this.#renderGrid(names);
+  }
+
+  #render() {
+    this.innerHTML = `
+      <div class="icon-set">
+        <label class="icon-set__search">
+          <span class="visually-hidden">Filter icons</span>
+          <input type="search" placeholder="Filter ${this.set} icons…">
+        </label>
+        <ul class="icon-set__grid" data-layout="grid" role="list"></ul>
+      </div>`;
+    const input = /** @type {HTMLInputElement} */ (this.querySelector('input'));
+    this.listen(input, 'input', (e) => this.#filter(/** @type {HTMLInputElement} */ (e.target).value));
+  }
+
+  #renderGrid(names) {
+    const ul = this.querySelector('.icon-set__grid');
+    if (!ul) return;
+    const esc = (s) => String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+    // Cells render with an empty, correctly-sized icon slot; the real icon
+    // (an <i data-icon>, whose CSS mask fetches the SVG) is mounted lazily
+    // below. Rendering a full set (~1900 icons) up front fires ~1900 concurrent
+    // fetches and exhausts the browser (net::ERR_INSUFFICIENT_RESOURCES).
+    ul.innerHTML = names.map((n) => `
+      <li data-icon-name="${esc(n)}">
+        <button type="button" title="Copy “${esc(n)}”" data-copy="${esc(n)}">
+          <span class="icon-set__icon" data-name="${esc(n)}"></span>
+          <span>${esc(n)}</span>
+        </button>
+      </li>`).join('');
+    this.listen(ul, 'click', (e) => {
+      const btn = /** @type {HTMLElement} */ (e.target).closest('[data-copy]');
+      if (btn) navigator.clipboard?.writeText(/** @type {HTMLElement} */ (btn).dataset.copy ?? '');
+    });
+
+    // Lazy-mount the icon only when a cell nears the viewport, so only the
+    // handful of visible icons fetch at a time instead of the whole set at once.
+    const set = this.set;
+    this.#io?.disconnect();
+    this.#io = new IntersectionObserver((entries, obs) => {
+      for (const entry of entries) {
+        if (!entry.isIntersecting) continue;
+        const slot = /** @type {HTMLElement} */ (entry.target);
+        obs.unobserve(slot);
+        if (slot.firstElementChild) continue; // already mounted
+        const icon = document.createElement('i');
+        icon.setAttribute('data-icon', slot.dataset.name ?? '');
+        icon.setAttribute('data-icon-set', set);
+        icon.setAttribute('aria-hidden', 'true');
+        slot.appendChild(icon);
+      }
+    }, { rootMargin: '400px' });
+    for (const slot of ul.querySelectorAll('.icon-set__icon')) this.#io.observe(slot);
+  }
+
+  #filter(q) {
+    const term = q.trim().toLowerCase();
+    for (const li of this.querySelectorAll('[data-icon-name]')) {
+      li.hidden = !!term && !(/** @type {HTMLElement} */ (li).dataset.iconName ?? '').toLowerCase().includes(term);
+    }
+  }
+}
+
+registerComponent('icon-set', IconSet);
+
+export { IconSet };

package/src/web-components/icon-set/static.html

@@ -0,0 +1,36 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Icon Set — Static Fallback</title>
+  <style>
+    body { font-family: system-ui, sans-serif; padding: 2rem; }
+    ul { list-style: none; margin: 0; padding: 0; display: grid; grid-template-columns: repeat(auto-fill, minmax(6rem, 1fr)); gap: 0.5rem; }
+    li { text-align: center; font-size: 0.75rem; color: #666; }
+  </style>
+</head>
+<body>
+  <!--
+    Static fallback for <icon-set>.
+
+    Upgrade relationship:
+    - Without JS: a plain list of icon names remains readable, so the
+      catalog's contents are never hidden from no-JS readers.
+    - With JS: the component replaces this with a filterable grid where
+      each cell renders the actual icon via <icon-wc> and a click copies
+      the name to the clipboard.
+  -->
+
+  <icon-set names="star home search settings heart check">
+    <ul>
+      <li>star</li>
+      <li>home</li>
+      <li>search</li>
+      <li>settings</li>
+      <li>heart</li>
+      <li>check</li>
+    </ul>
+  </icon-set>
+</body>
+</html>

package/src/web-components/icon-set/styles.css

@@ -0,0 +1,82 @@
+/* icon-set: Searchable icon catalog/browser with click-to-copy names */
+
+icon-set:not(:defined) {
+  display: block;
+}
+
+icon-set {
+  display: block;
+  font-family: var(--font-sans, system-ui);
+  color: var(--color-text, #1a1a1a);
+}
+
+@scope (icon-set) {
+  .icon-set__search input {
+    inline-size: 100%;
+    padding: var(--size-s, 0.5rem);
+    border: 1px solid var(--color-border, #d4d4d8);
+    border-radius: var(--radius-s, 0.25rem);
+    font: inherit;
+    color: inherit;
+    background: var(--color-surface, #fff);
+  }
+
+  /* data-layout="grid" on the <ul> lets vanilla-breeze reset the block-flow
+     li margin (which would otherwise skew the rows); these rules override the
+     primitive's defaults with the catalog's own dense column sizing + gap. */
+  .icon-set__grid {
+    list-style: none;
+    margin: var(--size-m, 1rem) 0 0;
+    padding: 0;
+    grid-template-columns: repeat(auto-fill, minmax(6rem, 1fr));
+    gap: var(--size-2xs, 0.25rem);
+  }
+
+  .icon-set__grid [hidden] {
+    display: none;
+  }
+
+  .icon-set__grid button {
+    inline-size: 100%;
+    block-size: 100%;        /* fill the cell so every card is the same height */
+    display: grid;
+    align-content: start;    /* icon + name anchored at the top, so icons line up */
+    justify-items: center;
+    gap: var(--size-2xs, 0.25rem);
+    padding: var(--size-s, 0.75rem);
+    background: none;
+    border: 1px solid transparent;
+    border-radius: var(--radius-s, 0.25rem);
+    cursor: pointer;
+    font-size: var(--font-size-xs, 0.75rem);
+    color: inherit;
+  }
+
+  /* Reserve two lines for the name so 1- and 2-line names produce equal-height
+     cards; long names wrap instead of overflowing their neighbours. */
+  .icon-set__grid button > span:last-child {
+    min-block-size: 2lh;
+    text-align: center;
+    overflow-wrap: anywhere;
+  }
+
+  .icon-set__grid button:hover {
+    border-color: var(--color-border, #d4d4d8);
+    background: var(--color-surface-2, #f4f4f5);
+  }
+
+  /* Reserve the icon box up front so the grid doesn't reflow as icons
+     lazily mount, and so each empty slot is observable/visible for the
+     IntersectionObserver. */
+  .icon-set__icon {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    inline-size: 1.5rem;
+    block-size: 1.5rem;
+  }
+
+  .icon-set__grid [data-icon] {
+    font-size: 1.5rem;
+  }
+}

package/src/web-components/icon-specimen/api.json

@@ -0,0 +1,46 @@
+{
+  "$schema": "../../../schemas/api.schema.json",
+  "element": "icon-specimen",
+  "type": "web-component",
+  "description": "Curated icon-language specimen: a fixed set of icon names rendered across the project's sizing scale.",
+  "htmlvalidate": {
+    "flow": true,
+    "permittedContent": [
+      "@flow"
+    ]
+  },
+  "attributes": [
+    {
+      "name": "set",
+      "kind": "host-api",
+      "purpose": "config",
+      "type": "string",
+      "description": "Icon set directory (default: \"lucide\")"
+    },
+    {
+      "name": "names",
+      "kind": "host-api",
+      "purpose": "config",
+      "type": "string",
+      "description": "Space/comma-separated list of icon names to display (required)."
+    },
+    {
+      "name": "data-sizes",
+      "kind": "host-api",
+      "purpose": "config",
+      "type": "string",
+      "description": "Space-separated sizing scale, e.g. \"1rem 1.5rem 2rem\" (default)."
+    }
+  ],
+  "childAttributes": [
+    {
+      "name": "name",
+      "kind": "host-api",
+      "purpose": "config",
+      "type": "string",
+      "element": "icon-wc",
+      "description": "Icon filename (without .svg), passed through from each specimen cell."
+    }
+  ],
+  "structure": []
+}