@birdapi/velinstyle 0.9.0 → 1.1.0

package/components/velin-form-summary.js

@@ -0,0 +1,348 @@
+import { announce } from './a11y-utils.js';
+
+/**
+ * Accessible error summary for a light-DOM `<form>`.
+ *
+ * Native constraint validation shows a transient browser bubble on one field at
+ * a time, which is unusable with a screen reader or on a long form. This element
+ * takes over submit handling to build a persistent, focusable summary, wire
+ * `aria-invalid` and `aria-describedby` per field, and announce the error count.
+ *
+ * Covers WCAG 3.3.1 Error Identification, 3.3.3 Error Suggestion and the
+ * `aria-describedby` half of 4.1.2 Name, Role, Value.
+ */
+
+const FIELD_SELECTOR = 'input, select, textarea';
+const IGNORED_TYPES = new Set(['submit', 'reset', 'button', 'image', 'hidden']);
+
+let fieldIdCounter = 0;
+
+/** `CSS.escape` is missing in some non-browser DOM implementations. */
+function escapeSelector(value) {
+  const text = String(value ?? '');
+  if (typeof CSS !== 'undefined' && typeof CSS.escape === 'function') return CSS.escape(text);
+  return text.replace(/[^\w-]/g, (char) => `\\${char}`);
+}
+
+/** @param {HTMLElement} field */
+function fieldLabel(field) {
+  const explicit = field.getAttribute('data-error-label');
+  if (explicit) return explicit;
+
+  const ariaLabel = field.getAttribute('aria-label');
+  if (ariaLabel?.trim()) return ariaLabel.trim();
+
+  const labelledBy = field.getAttribute('aria-labelledby');
+  if (labelledBy) {
+    const text = labelledBy
+      .split(/\s+/)
+      .map((id) => field.ownerDocument.getElementById(id)?.textContent?.trim() || '')
+      .filter(Boolean)
+      .join(' ');
+    if (text) return text;
+  }
+
+  if (field.id) {
+    const label = field.ownerDocument.querySelector(`label[for="${escapeSelector(field.id)}"]`);
+    if (label?.textContent.trim()) return label.textContent.trim();
+  }
+
+  const wrapping = field.closest('label');
+  if (wrapping?.textContent.trim()) return wrapping.textContent.trim();
+
+  return field.name || 'This field';
+}
+
+/** @param {HTMLElement} field */
+function fieldMessage(field) {
+  return field.getAttribute('data-error-message')?.trim() || field.validationMessage || 'Invalid value';
+}
+
+/**
+ * @param {HTMLElement} field
+ * @param {string} id
+ */
+function addDescribedBy(field, id) {
+  const ids = (field.getAttribute('aria-describedby') || '').split(/\s+/).filter(Boolean);
+  if (!ids.includes(id)) {
+    ids.push(id);
+    field.setAttribute('aria-describedby', ids.join(' '));
+  }
+}
+
+/**
+ * @param {HTMLElement} field
+ * @param {string} id
+ */
+function removeDescribedBy(field, id) {
+  const ids = (field.getAttribute('aria-describedby') || '').split(/\s+/).filter(Boolean);
+  const next = ids.filter((value) => value !== id);
+  if (next.length) field.setAttribute('aria-describedby', next.join(' '));
+  else field.removeAttribute('aria-describedby');
+}
+
+class VelinFormSummary extends HTMLElement {
+  static get observedAttributes() {
+    return ['for', 'heading'];
+  }
+
+  constructor() {
+    super();
+    this._form = null;
+    this._panel = null;
+    this._errors = [];
+    this._onSubmit = this._onSubmit.bind(this);
+    this._onFieldChange = this._onFieldChange.bind(this);
+    this._onReset = this._onReset.bind(this);
+  }
+
+  connectedCallback() {
+    this.classList.add('velin-form-summary');
+    requestAnimationFrame(() => this._bindForm());
+  }
+
+  disconnectedCallback() {
+    this._unbindForm();
+  }
+
+  attributeChangedCallback(name, previous, next) {
+    if (previous === next) return;
+    if (name === 'for' && this.isConnected) {
+      this._unbindForm();
+      this._bindForm();
+    } else if (name === 'heading' && this._panel) {
+      const heading = this._panel.querySelector('.velin-form-summary__heading');
+      if (heading) heading.textContent = this.headingText;
+    }
+  }
+
+  // ── Public API ─────────────────────────────────────────────────────────────
+
+  get form() {
+    return this._form;
+  }
+
+  /** @returns {{ field: HTMLElement, label: string, message: string }[]} */
+  get errors() {
+    return this._errors.slice();
+  }
+
+  get headingText() {
+    return this.getAttribute('heading') || 'There is a problem';
+  }
+
+  /** Validate the form and render the summary. @returns {boolean} valid */
+  validate() {
+    if (!this._form) return true;
+    const errors = [];
+    for (const field of this._fields()) {
+      if (field.checkValidity()) {
+        this._clearFieldError(field);
+        continue;
+      }
+      const error = { field, label: fieldLabel(field), message: fieldMessage(field) };
+      this._markFieldError(field, error.message);
+      errors.push(error);
+    }
+    this._errors = errors;
+    this._render();
+    return errors.length === 0;
+  }
+
+  /** Remove the summary and all field error state. */
+  clear() {
+    for (const field of this._fields()) this._clearFieldError(field);
+    this._errors = [];
+    this._render();
+  }
+
+  /** Move focus to the first field with an error. */
+  focusFirstError() {
+    const first = this._errors[0];
+    if (first) this._focusField(first.field);
+  }
+
+  // ── Form wiring ────────────────────────────────────────────────────────────
+
+  _bindForm() {
+    const id = this.getAttribute('for');
+    this._form = id ? this.ownerDocument.getElementById(id) : this.closest('form');
+    if (!this._form) return;
+
+    // Native bubbles show one error at a time and vanish; the summary replaces them.
+    if (!this.hasAttribute('native-validation')) this._form.noValidate = true;
+
+    this._form.addEventListener('submit', this._onSubmit);
+    this._form.addEventListener('reset', this._onReset);
+    this._form.addEventListener('input', this._onFieldChange);
+    this._form.addEventListener('change', this._onFieldChange);
+  }
+
+  _unbindForm() {
+    if (!this._form) return;
+    this._form.removeEventListener('submit', this._onSubmit);
+    this._form.removeEventListener('reset', this._onReset);
+    this._form.removeEventListener('input', this._onFieldChange);
+    this._form.removeEventListener('change', this._onFieldChange);
+    this._form = null;
+  }
+
+  /** @returns {HTMLElement[]} */
+  _fields() {
+    if (!this._form) return [];
+    const seenRadioNames = new Set();
+    return [...this._form.querySelectorAll(FIELD_SELECTOR)].filter((field) => {
+      if (IGNORED_TYPES.has(field.type)) return false;
+      if (field.disabled || field.hasAttribute('data-error-ignore')) return false;
+      if (typeof field.checkValidity !== 'function') return false;
+      // One entry per radio group so the summary lists the group once.
+      if (field.type === 'radio' && field.name) {
+        if (seenRadioNames.has(field.name)) return false;
+        seenRadioNames.add(field.name);
+      }
+      return true;
+    });
+  }
+
+  _onSubmit(event) {
+    if (this.validate()) return;
+    event.preventDefault();
+    this._announceErrors();
+    this._focusPanel();
+    this.dispatchEvent(new CustomEvent('velin-form-invalid', {
+      bubbles: true,
+      detail: { errors: this.errors.map(({ label, message }) => ({ label, message })) },
+    }));
+  }
+
+  _onReset() {
+    requestAnimationFrame(() => this.clear());
+  }
+
+  /** Re-validate a single field once it already had an error, never before. */
+  _onFieldChange(event) {
+    const field = event.target;
+    if (!field || !this._errors.some((error) => error.field === field)) return;
+    if (!field.checkValidity()) return;
+
+    this._clearFieldError(field);
+    this._errors = this._errors.filter((error) => error.field !== field);
+    this._render();
+    if (this._errors.length === 0) {
+      this.dispatchEvent(new CustomEvent('velin-form-valid', { bubbles: true }));
+    }
+  }
+
+  // ── Field state ────────────────────────────────────────────────────────────
+
+  /** @param {HTMLElement} field */
+  _errorId(field) {
+    if (!field.id) field.id = `velin-field-${++fieldIdCounter}`;
+    return `${field.id}-error`;
+  }
+
+  /**
+   * @param {HTMLElement} field
+   * @param {string} message
+   */
+  _markFieldError(field, message) {
+    const errorId = this._errorId(field);
+    field.setAttribute('aria-invalid', 'true');
+
+    let holder = this.ownerDocument.getElementById(errorId);
+    if (!holder) {
+      holder = this._form.querySelector(`[data-velin-error-for="${escapeSelector(field.name || field.id)}"]`);
+    }
+    if (!holder) {
+      holder = this.ownerDocument.createElement('p');
+      holder.dataset.velinErrorGenerated = 'true';
+      field.insertAdjacentElement('afterend', holder);
+    }
+    holder.id = errorId;
+    holder.classList.add('velin-field-error');
+    holder.textContent = message;
+    addDescribedBy(field, errorId);
+  }
+
+  /** @param {HTMLElement} field */
+  _clearFieldError(field) {
+    if (!field.id) return;
+    const errorId = `${field.id}-error`;
+    field.removeAttribute('aria-invalid');
+    removeDescribedBy(field, errorId);
+
+    const holder = this.ownerDocument.getElementById(errorId);
+    if (!holder) return;
+    if (holder.dataset.velinErrorGenerated) holder.remove();
+    else holder.textContent = '';
+  }
+
+  /** @param {HTMLElement} field */
+  _focusField(field) {
+    const target = field.type === 'radio' && field.name
+      ? this._form.querySelector(`input[type="radio"][name="${escapeSelector(field.name)}"]`) || field
+      : field;
+    target.focus();
+    this.dispatchEvent(new CustomEvent('velin-form-error-focus', {
+      bubbles: true,
+      detail: { name: target.name || target.id },
+    }));
+  }
+
+  // ── Summary panel ──────────────────────────────────────────────────────────
+
+  _render() {
+    if (!this._errors.length) {
+      this._panel?.remove();
+      this._panel = null;
+      this.hidden = true;
+      return;
+    }
+
+    this.hidden = false;
+    if (!this._panel?.isConnected) {
+      const panel = this.ownerDocument.createElement('div');
+      panel.className = 'velin-form-summary__panel velin-alert velin-alert--danger';
+      panel.setAttribute('role', 'alert');
+      panel.tabIndex = -1;
+
+      const heading = this.ownerDocument.createElement('p');
+      heading.className = 'velin-form-summary__heading';
+      heading.textContent = this.headingText;
+
+      const list = this.ownerDocument.createElement('ul');
+      list.className = 'velin-form-summary__list';
+
+      panel.append(heading, list);
+      this.appendChild(panel);
+      this._panel = panel;
+    }
+
+    const list = this._panel.querySelector('.velin-form-summary__list');
+    list.textContent = '';
+    for (const error of this._errors) {
+      const item = this.ownerDocument.createElement('li');
+      const link = this.ownerDocument.createElement('a');
+      link.href = `#${this._errorId(error.field).replace(/-error$/, '')}`;
+      link.textContent = `${error.label}: ${error.message}`;
+      link.addEventListener('click', (event) => {
+        event.preventDefault();
+        this._focusField(error.field);
+      });
+      item.appendChild(link);
+      list.appendChild(item);
+    }
+  }
+
+  _focusPanel() {
+    this._panel?.focus();
+  }
+
+  _announceErrors() {
+    const count = this._errors.length;
+    announce(count === 1 ? '1 field needs attention' : `${count} fields need attention`, 'assertive');
+  }
+}
+
+customElements.define('velin-form-summary', VelinFormSummary);
+export default VelinFormSummary;

package/core/a11y/component-contracts.json

@@ -1,6 +1,6 @@
 {
   "wcagLevel": "AAA",
-  "version": "0.9.0",
+  "version": "1.1.0",
   "components": {
     "velin-accordion": {
       "status": "pass",
@@ -74,6 +74,15 @@
       "keyboard": "N/A",
       "reducedMotion": true
     },
+    "velin-data-table": {
+      "status": "pass",
+      "roles": ["button"],
+      "keyboard": "Native buttons for column sort and pagination",
+      "liveRegion": "polite",
+      "reducedMotion": true,
+      "requiredAttributes": [],
+      "notes": "Enhances a light-DOM table. Sort state exposed via aria-sort; sort triggers are real buttons. Needs a caption, aria-label, or label attribute (warns otherwise). Filtered and off-page rows use hidden so they leave the a11y tree; sort, filter and page changes are announced."
+    },
     "velin-dialog": {
       "status": "pass",
       "roles": ["dialog"],
@@ -97,6 +106,14 @@
       "roles": ["button"],
       "requiredAttributes": ["aria-label"]
     },
+    "velin-form-summary": {
+      "status": "pass",
+      "roles": ["alert", "link"],
+      "keyboard": "Summary links move focus to the offending field",
+      "liveRegion": "assertive",
+      "requiredAttributes": [],
+      "notes": "Disables native validation bubbles and renders a focusable role=alert summary. Sets aria-invalid and wires aria-describedby to per-field messages (WCAG 3.3.1, 3.3.3, 4.1.2). Field errors clear as soon as the field becomes valid."
+    },
     "velin-icon": {
       "status": "pass",
       "roles": ["img", "presentation"],

package/core/highlight/languages/go.js

@@ -0,0 +1,28 @@
+/** @import { LexerFn } from '../types.js' */
+import { tokenize } from './_utils.js';
+
+const RULES = [
+  { type: 'comment', re: /\/\/[^\n]*/y },
+  { type: 'comment', re: /\/\*[\s\S]*?\*\//y },
+  // Raw strings may span lines.
+  { type: 'string', re: /`[^`]*`/y },
+  { type: 'string', re: /"(?:\\.|[^"\\\n])*"/y },
+  { type: 'string', re: /'(?:\\.|[^'\\\n])*'/y },
+  { type: 'number', re: /\b0[xX][\da-fA-F_]+\b|\b\d[\d_]*(?:\.[\d_]*)?(?:[eE][+-]?\d+)?i?\b/y },
+  {
+    type: 'keyword',
+    re: /\b(?:break|case|chan|const|continue|default|defer|else|fallthrough|for|func|go|goto|if|import|interface|map|package|range|return|select|struct|switch|type|var)\b/y,
+  },
+  {
+    type: 'builtin',
+    re: /\b(?:append|bool|byte|cap|clear|close|complex|complex64|complex128|copy|delete|error|float32|float64|imag|int|int8|int16|int32|int64|len|make|max|min|new|nil|panic|print|println|real|recover|rune|string|true|false|iota|uint|uint8|uint16|uint32|uint64|uintptr|any)\b/y,
+  },
+  { type: 'operator', re: /:=|\.\.\.|&&|\|\||<-|\+\+|--|<<=?|>>=?|&\^=?|[-+*/%&|^<>!=]=?|~/y },
+  { type: 'punctuation', re: /[[\]{}(),;:.]/y },
+  { type: 'identifier', re: /\b[A-Za-z_]\w*\b/y },
+];
+
+/** @type {LexerFn} */
+export default function lexGo(code) {
+  return tokenize(code, RULES);
+}

package/core/highlight/languages/python.js

@@ -0,0 +1,29 @@
+/** @import { LexerFn } from '../types.js' */
+import { tokenize } from './_utils.js';
+
+const RULES = [
+  { type: 'comment', re: /#[^\n]*/y },
+  // Triple-quoted strings first so the single-quote rules cannot split them.
+  { type: 'string', re: /[rbfu]{0,2}"""[\s\S]*?"""/y },
+  { type: 'string', re: /[rbfu]{0,2}'''[\s\S]*?'''/y },
+  { type: 'string', re: /[rbfu]{0,2}"(?:\\.|[^"\\\n])*"/y },
+  { type: 'string', re: /[rbfu]{0,2}'(?:\\.|[^'\\\n])*'/y },
+  { type: 'number', re: /\b0[xX][\da-fA-F_]+\b|\b\d[\d_]*(?:\.[\d_]+)?(?:[eE][+-]?\d+)?j?\b/y },
+  {
+    type: 'keyword',
+    re: /\b(?:and|as|assert|async|await|break|class|continue|def|del|elif|else|except|finally|for|from|global|if|import|in|is|lambda|match|nonlocal|not|or|pass|raise|return|try|while|with|yield)\b/y,
+  },
+  {
+    type: 'builtin',
+    re: /\b(?:None|True|False|self|cls|abs|all|any|bool|bytes|dict|dir|enumerate|filter|float|format|frozenset|getattr|hasattr|int|isinstance|issubclass|iter|len|list|map|max|min|next|object|open|print|range|repr|reversed|round|set|setattr|sorted|str|sum|super|tuple|type|zip)\b/y,
+  },
+  // Multi-character operators first so `->` is not split into `-` and `>`.
+  { type: 'operator', re: /->|:=|\*\*=?|\/\/=?|<<=?|>>=?|[-+*/%&|^~<>!=]=?/y },
+  { type: 'punctuation', re: /[[\]{}(),:;.@]/y },
+  { type: 'identifier', re: /\b[A-Za-z_]\w*\b/y },
+];
+
+/** @type {LexerFn} */
+export default function lexPython(code) {
+  return tokenize(code, RULES);
+}

package/core/highlight/languages/rust.js

@@ -0,0 +1,32 @@
+/** @import { LexerFn } from '../types.js' */
+import { tokenize } from './_utils.js';
+
+const RULES = [
+  { type: 'comment', re: /\/\/\/?[^\n]*/y },
+  { type: 'comment', re: /\/\*[\s\S]*?\*\//y },
+  // Raw strings close on the same number of hashes they opened with.
+  { type: 'string', re: /b?r(#*)"[\s\S]*?"\1/y },
+  { type: 'string', re: /b?"(?:\\.|[^"\\])*"/y },
+  { type: 'string', re: /b?'(?:\\.|[^'\\])'/y },
+  // Attributes such as #[derive(Debug)] read as annotations.
+  { type: 'builtin', re: /#!?\[[^\]]*\]/y },
+  { type: 'number', re: /\b0[xXbo][\da-fA-F_]+\b|\b\d[\d_]*(?:\.[\d_]+)?(?:[eE][+-]?\d+)?(?:[iuf](?:8|16|32|64|128|size))?\b/y },
+  {
+    type: 'keyword',
+    re: /\b(?:as|async|await|break|const|continue|crate|dyn|else|enum|extern|fn|for|if|impl|in|let|loop|match|mod|move|mut|pub|ref|return|self|Self|static|struct|super|trait|type|unsafe|use|where|while)\b/y,
+  },
+  {
+    type: 'builtin',
+    re: /\b(?:bool|char|f32|f64|i8|i16|i32|i64|i128|isize|str|u8|u16|u32|u64|u128|usize|String|Vec|Option|Result|Some|None|Ok|Err|Box|Rc|Arc|true|false)\b/y,
+  },
+  // Lifetimes such as 'a must not be read as an unterminated char literal.
+  { type: 'operator', re: /'[a-z_]\w*\b/y },
+  { type: 'operator', re: /=>|->|::|\.\.=?|&&|\|\||<<=?|>>=?|[-+*/%&|^<>!=]=?|[?@]/y },
+  { type: 'punctuation', re: /[[\]{}(),;:.#]/y },
+  { type: 'identifier', re: /\b[A-Za-z_]\w*!?\b/y },
+];
+
+/** @type {LexerFn} */
+export default function lexRust(code) {
+  return tokenize(code, RULES);
+}

package/core/highlight/languages/yaml.js

@@ -0,0 +1,23 @@
+/** @import { LexerFn } from '../types.js' */
+import { tokenize } from './_utils.js';
+
+const RULES = [
+  { type: 'comment', re: /#[^\n]*/y },
+  // Document markers and block scalar indicators.
+  { type: 'punctuation', re: /^(?:---|\.\.\.)$/my },
+  { type: 'string', re: /"(?:\\.|[^"\\])*"/y },
+  { type: 'string', re: /'(?:''|[^'])*'/y },
+  // Keys are the primary structure in YAML, so they get the attr-name colour.
+  { type: 'attr-name', re: /^[ \t]*-?[ \t]*[\w.$-]+(?=[ \t]*:(?:[ \t]|$))/my },
+  { type: 'punctuation', re: /^[ \t]*-(?=[ \t]|$)/my },
+  { type: 'keyword', re: /\b(?:true|false|null|yes|no|on|off|~)\b/yi },
+  { type: 'number', re: /\b-?\d+(?:\.\d+)?(?:[eE][+-]?\d+)?\b/y },
+  // Anchors, aliases, tags and block scalar headers.
+  { type: 'operator', re: /[&*]\w+|![\w/!-]*|[|>][+-]?\d*(?=\s*$)/my },
+  { type: 'punctuation', re: /[:,[\]{}]/y },
+];
+
+/** @type {LexerFn} */
+export default function lexYaml(code) {
+  return tokenize(code, RULES);
+}

package/core/highlight/registry.js

@@ -28,6 +28,14 @@ const LAZY_LOADERS = {
   console: () => import('./languages/plain.js'),
   php: () => import('./languages/php.js'),
   blade: () => import('./languages/blade.js'),
+  python: () => import('./languages/python.js'),
+  py: () => import('./languages/python.js'),
+  yaml: () => import('./languages/yaml.js'),
+  yml: () => import('./languages/yaml.js'),
+  go: () => import('./languages/go.js'),
+  golang: () => import('./languages/go.js'),
+  rust: () => import('./languages/rust.js'),
+  rs: () => import('./languages/rust.js'),
 };
 
 /** @param {string} name */
@@ -49,11 +57,14 @@ export function normalizeLanguage(name) {
     md: 'markdown',
     plaintext: 'text',
     'plain-text': 'text',
-    yml: 'text',
-    yaml: 'text',
+    yml: 'yaml',
     toml: 'text',
     ini: 'text',
     php8: 'php',
+    py: 'python',
+    python3: 'python',
+    golang: 'go',
+    rs: 'rust',
   };
   return map[n] || n;
 }

package/core/meta/build.js

@@ -85,7 +85,7 @@ export function buildPageMeta(html, sourcePath = '', pkgRoot = '.') {
       : 'page';
 
   return {
-    version: readPackageMeta(pkgRoot).version || '0.9.0',
+    version: readPackageMeta(pkgRoot).version || '0.0.0',
     mime: VELIN_META_MIME,
     page: {
       intent,

package/core/search/worker-client.js

@@ -5,10 +5,9 @@ let _nextId = 0;
  */
 export function createSearchWorker(workerUrl) {
   if (typeof Worker === 'undefined') return null;
+  if (!workerUrl) return null;
 
-  const url =
-    workerUrl ||
-    new URL('./worker.js', import.meta.url).href;
+  const url = workerUrl;
 
   let worker;
   try {