@blukavantui/community 0.0.0-stage → 1.1.0

package/src/component-factories/upload-manager.ts

@@ -0,0 +1,76 @@
+import {installUploadManager} from '../runtime/upload-manager.js';
+import { mountRoot, node, slot } from "../dom.js";
+import type * as T from "../types.js";
+type RawEvents = Record<string, (...args: any[]) => unknown>;
+type Raw = {
+  sync(id: string, options: object, events: RawEvents, owner: string): string;
+  destroy(owner: string): void;
+};
+function runtime(): Record<string, Raw> {
+  if (typeof window === "undefined")
+    throw new Error("Mount BluKavantUI in a browser, after the host is connected.");
+  return (window as unknown as { BluUICommunityRuntime: Record<string, Raw> })
+    .BluUICommunityRuntime;
+}
+function bind<P extends object>(
+  host: HTMLElement,
+  kind: string,
+  initial: P,
+  map: (p: P) => object,
+  events: (remember: (p: Partial<P>) => void) => RawEvents,
+  setup?: (root: HTMLElement, p: P) => void,
+): T.Component<P> {
+  const r = mountRoot(host),
+    key = r.id;
+  let props = { ...initial },
+    disposed = false;
+  const raw = runtime()[kind],
+    callbacks = events((p) => {
+      props = { ...props, ...p };
+    });
+  const update = (patch: Partial<P>) => {
+    if (disposed) throw new Error("Component is destroyed.");
+    props = { ...props, ...patch };
+    setup?.(r, props);
+    const error = raw.sync(r.id, map(props), callbacks, key);
+    if (error) throw new Error(error);
+  };
+  try {
+    update({});
+  } catch (e) {
+    raw.destroy(key);
+    r.remove();
+    throw e;
+  }
+  return {
+    element: r,
+    update,
+    destroy() {
+      if (disposed) return;
+      disposed = true;
+      raw.destroy(key);
+      r.remove();
+    },
+  };
+}
+export function createUploadManager(
+  host: HTMLElement,
+  options: T.UploadManagerOptions,
+  events: T.UploadManagerEvents = {},
+) {
+ installUploadManager();
+  return bind(
+    host,
+    "UploadManager",
+    options,
+    (p) => {
+      const { Headers, ...rest } = p;
+      return { ...rest, HeadersJson: JSON.stringify(Headers || {}) };
+    },
+    () => ({
+      QueueChanged: (j) => events.QueueChanged?.(JSON.parse(j)),
+      Uploaded: (key, name, response) => events.Uploaded?.(key, name, response),
+      Error: (message) => events.Error?.(message),
+    }),
+  );
+}

package/src/component-factories/video-lightbox.ts

@@ -0,0 +1,5 @@
+import {installVideoLightbox} from '../runtime/video-lightbox.js';
+import {bind} from "../component-runtime.js";
+import type * as T from "../types.js";
+export function createVideoLightbox(host:HTMLElement, options:T.VideoLightboxOptions, events:T.VideoLightboxEvents={}) {
+ installVideoLightbox();return bind<T.VideoLightboxOptions>(host,"VideoLightbox",{...{"ControlColor": "Primary", "ShowPauseGlass": true, "SourceUrl": "", "PosterUrl": "", "CaptionsUrl": "", "CaptionLanguage": "en", "Title": "Video", "IsLooping": false, "IsMuted": false, "IsRounded": false, "MediaId": "", "ShowViewingHeatmap": false, "ViewingHeatmap": [], "AllowPictureInPicture": true, "AspectRatio": "16 / 9", "IsOpen": false, "PlayLabel": "Watch the film", "ShowPoster": true, "AccessibleLabel": "", "ExtendedClass": ""},...options},remember=>({PlaybackChanged: (state) => events.PlaybackChanged?.(state),ViewingActivity: (raw) => events.ViewingActivity?.(JSON.parse(raw) as T.BluVideoViewingActivity),OpenChanged: (isOpen) => {remember({IsOpen:isOpen});return events.OpenChanged?.(isOpen);},Error: (message) => {return events.Error?.(message);}}),["ViewingHeatmap"],[]);}

package/src/component-factories/video-player.ts

@@ -0,0 +1,5 @@
+import {installVideoPlayer} from '../runtime/video-player.js';
+import {bind} from "../component-runtime.js";
+import type * as T from "../types.js";
+export function createVideoPlayer(host:HTMLElement, options:T.VideoPlayerOptions, events:T.VideoPlayerEvents={}) {
+ installVideoPlayer();return bind<T.VideoPlayerOptions>(host,"VideoPlayer",{...{"ControlColor": "Primary", "ShowPauseGlass": true, "SourceUrl": "", "PosterUrl": "", "CaptionsUrl": "", "CaptionLanguage": "en", "Title": "Video", "IsLooping": false, "IsMuted": false, "IsRounded": false, "MediaId": "", "ShowViewingHeatmap": false, "ViewingHeatmap": [], "AllowPictureInPicture": true, "AspectRatio": "16 / 9", "AccessibleLabel": "", "ExtendedClass": ""},...options},remember=>({ViewingActivity: (raw) => events.ViewingActivity?.(JSON.parse(raw) as T.BluVideoViewingActivity),PlaybackChanged: (state) => {return events.PlaybackChanged?.(state);},Error: (message) => {return events.Error?.(message);}}),["ViewingHeatmap"],[]);}

package/src/component-runtime.ts

@@ -0,0 +1,20 @@
+import { mountRoot, node } from "./dom.js";
+import type { Component, Slot } from "./types.js";
+type Raw = {sync(id:string, options:object, events:Record<string,(...args:any[])=>unknown>,key:string):string;destroy(key:string):void};
+export function bind<P extends object>(host:HTMLElement,kind:string,initial:P,callbacks:(remember:(patch:Partial<P>)=>void)=>Record<string,(...args:any[])=>unknown>,listNames:string[]=[],slotNames:string[]=[]):Component<P>{
+ const root=mountRoot(host), key=root.id; let props={...initial},disposed=false;
+ const rt=(window as unknown as {BluUICommunityRuntime:Record<string,Raw>}).BluUICommunityRuntime[kind];
+ const slots=new Map<string,{element:HTMLElement,value:Slot|undefined}>();
+ for(const name of slotNames){const element=node("div","blu-common-slot--"+name.toLowerCase());root.append(element);slots.set(name,{element,value:undefined});}
+ const events=callbacks(p=>{props={...props,...p};});
+ const update=(patch:Partial<P>)=>{if(disposed)throw Error("Component is destroyed.");props={...props,...patch};const raw={...props} as Record<string,unknown>;
+  for(const name of listNames){raw[name+"Json"]=JSON.stringify(raw[name]||[]);delete raw[name];}
+  if("PageSizes" in raw){raw.PageSizesJson=JSON.stringify(raw.PageSizes);delete raw.PageSizes;}
+  root.classList.toggle("blu-common-has-actions",!!raw.Actions);
+  for(const[name,slot]of slots){const value=raw[name] as Slot|undefined;if(slot.value!==value){slot.element.replaceChildren();if(value!==undefined)slot.element.append(value);slot.value=value;}delete raw[name];}
+  if(raw.ExtendedClass)String(raw.ExtendedClass).split(/\s+/).filter(Boolean).forEach(c=>root.classList.add(c));
+  const error=rt.sync(key,raw,events,key);if(error)throw Error(error);
+ };
+ try{update({});}catch(e){rt.destroy(key);root.remove();throw e;}
+ return {element:root,update,destroy(){if(disposed)return;disposed=true;rt.destroy(key);root.remove();}};
+}

package/src/content-carousel.ts

@@ -0,0 +1,2 @@
+export * from './component-factories/content-carousel.js';
+export type * from './types.js';

package/src/content.ts

@@ -0,0 +1,13 @@
+export * from './video-player.js';
+export * from './video-lightbox.js';
+export * from './media-image.js';
+export * from './media-card.js';
+export * from './image-compare.js';
+export * from './text-highlight.js';
+export * from './content-carousel.js';
+export * from './profile-card.js';
+export * from './quote-card.js';
+export * from './collection-layout.js';
+export * from './hero-section.js';
+export * from './split-section.js';
+export * from './logo-cloud.js';

package/src/core.ts

@@ -0,0 +1,6 @@
+export * from './button.js';
+export * from './badge.js';
+export * from './chip.js';
+export * from './skeleton.js';
+export * from './font-provider.js';
+export * from './chip-group.js';

package/src/dashboard-canvas.ts

@@ -0,0 +1,2 @@
+export * from './component-factories/dashboard-canvas.js';
+export type * from './types.js';

package/src/dashboard-panel.ts

@@ -0,0 +1,2 @@
+export * from './component-factories/dashboard-panel.js';
+export type * from './types.js';

package/src/data.ts

@@ -0,0 +1,10 @@
+export * from './tree-view.js';
+export * from './timeline.js';
+export * from './pagination.js';
+export * from './statistic.js';
+export * from './qr-code.js';
+export * from './descriptions.js';
+export * from './sparkline.js';
+export * from './dashboard-canvas.js';
+export * from './dashboard-panel.js';
+export * from './table.js';

package/src/date-picker.ts

@@ -0,0 +1,2 @@
+export * from './component-factories/date-picker.js';
+export type * from './types.js';

package/src/date-range-picker.ts

@@ -0,0 +1,2 @@
+export * from './component-factories/date-range-picker.js';
+export type * from './types.js';

package/src/date-time-picker.ts

@@ -0,0 +1,2 @@
+export * from './component-factories/date-time-picker.js';
+export type * from './types.js';

package/src/descriptions.ts

@@ -0,0 +1,2 @@
+export * from './component-factories/descriptions.js';
+export type * from './types.js';

package/src/dom.ts

@@ -0,0 +1,65 @@
+import type { Component, Slot } from "./types.js";
+export function node<K extends keyof HTMLElementTagNameMap>(
+  tag: K,
+  className = "",
+  text?: string,
+): HTMLElementTagNameMap[K] {
+  const n = document.createElement(tag);
+  n.className = className;
+  if (text !== undefined) n.textContent = text;
+  return n;
+}
+export function slot(parent: HTMLElement, content?: Slot) {
+  if (content !== undefined) parent.append(content);
+}
+export function mountRoot(host: HTMLElement) {
+  if (!host.isConnected)
+    throw new Error("Mount BluUI into an element connected to the document.");
+  const root = node("div");
+  root.id = "bluui-community-" + crypto.randomUUID();
+  host.append(root);
+  return root;
+}
+export function component<P extends object>(
+  host: HTMLElement,
+  initial: P,
+  paint: (
+    root: HTMLElement,
+    props: P,
+    update: (patch: Partial<P>) => void,
+  ) => void,
+): Component<P> {
+  const root = mountRoot(host);
+  let props = { ...initial },
+    disposed = false;
+  const update = (patch: Partial<P>) => {
+    if (disposed) throw new Error("Component is destroyed.");
+    props = { ...props, ...patch };
+    paint(root, props, update);
+  };
+  try {
+    update({});
+  } catch (error) {
+    root.remove();
+    throw error;
+  }
+  return {
+    element: root,
+    update,
+    destroy() {
+      if (disposed) return;
+      disposed = true;
+      root.remove();
+    },
+  };
+}
+export function classes(base: string, extra?: string) {
+  return base + (extra ? " " + extra : "");
+}
+
+export function safeUrl(value: string) {
+  const u = new URL(value, document.baseURI);
+  if (!["https:", "http:", "mailto:", "tel:"].includes(u.protocol))
+    throw new Error("Unsupported link protocol.");
+  return value;
+}

package/src/drawer.ts

@@ -0,0 +1,2 @@
+export * from './component-factories/drawer.js';
+export type * from './types.js';

package/src/empty-state.ts

@@ -0,0 +1,2 @@
+export {createEmptyState} from './essentials.js';
+export type * from './types.js';

package/src/essentials.ts

@@ -0,0 +1,180 @@
+import {installEmptyState} from './runtime/empty-state.js';
+import {bind} from './component-runtime.js';
+import {node, slot, component, classes} from "./dom.js";
+import type {ButtonOptions, ButtonEvents, BadgeOptions, ChipOptions, ChipEvents, CardOptions, SkeletonOptions, ChipGroupOptions, EmptyStateOptions, EmptyStateEvents} from "./types.js";
+export function buttonElement(p: ButtonOptions, events: ButtonEvents = {}) {
+  const b = node(
+    "button",
+    classes(
+      `blu-button blu-button--${(p.Color || "Primary").toLowerCase()} blu-button--${(p.Variant || "Filled").toLowerCase()} blu-button--${(p.Size || "Medium").toLowerCase()}${p.IsFullWidth ? " blu-button--full" : ""}${p.IsDisabled ? " blu-button--disabled" : ""}${p.IsLoading ? " blu-button--loading" : ""}`,
+      p.ExtendedClass,
+    ),
+  );
+  b.type = "button";
+  if (p.AccessibleLabel) b.setAttribute("aria-label", p.AccessibleLabel);
+  if (p.IsExpandable) b.setAttribute("aria-expanded", String(!!p.IsExpanded));
+  if (p.ControlsId) b.setAttribute("aria-controls", p.ControlsId);
+  if (p.IsCurrentPage) b.setAttribute("aria-current", "page");
+  b.disabled = !!(p.IsDisabled || p.IsLoading);
+  if (p.IsLoading) {
+    b.setAttribute("aria-busy", "true");
+    b.setAttribute("aria-label", (p.AccessibleLabel || p.Label) + " (loading)");
+    const spinner = node("span", "blu-button__spinner");
+    spinner.setAttribute("aria-hidden", "true");
+    b.append(spinner);
+  }
+  b.append(node("span", "blu-button__content", p.Label));
+  b.onclick = (e) => {
+    void events.Click?.(e);
+  };
+  return b;
+}
+export function createButton(
+  host: HTMLElement,
+  options: ButtonOptions,
+  events: ButtonEvents = {},
+) {
+  return component(host, options, (r, p) => {
+    const focused = r.contains(document.activeElement);
+    r.replaceChildren(buttonElement(p, events));
+    if (focused) r.querySelector("button")?.focus();
+  });
+}
+
+export function createBadge(host: HTMLElement, options: BadgeOptions) {
+  return component(host, options, (r, p) => {
+    const n = node(
+      "span",
+      classes(
+        "blu-badge blu-badge--" + (p.Color || "Primary").toLowerCase(),
+        p.ExtendedClass,
+      ),
+    );
+    n.append(node("span", "blu-badge__label", p.Label));
+    r.replaceChildren(n);
+  });
+}
+
+export function createChip(
+  host: HTMLElement,
+  options: ChipOptions,
+  events: ChipEvents = {},
+) {
+  return component(host, options, (r, p, update) => {
+    const focused = r.contains(document.activeElement),
+      c = node(
+        "div",
+        classes(
+          "blu-chip blu-chip--" +
+            (p.Color || "Default").toLowerCase() +
+            (p.IsSelected ? " blu-chip--selected" : "") +
+            (p.IsDisabled ? " blu-chip--disabled" : ""),
+          p.ExtendedClass,
+        ),
+      );
+    if (p.IsSelectable) {
+      const b = node("button", "blu-chip__select", p.Label);
+      b.type = "button";
+      b.disabled = !!p.IsDisabled;
+      b.setAttribute("aria-pressed", String(!!p.IsSelected));
+      b.onclick = () => {
+        update({ IsSelected: !p.IsSelected });
+        void events.SelectionChanged?.(!p.IsSelected);
+      };
+      c.append(b);
+    } else c.append(node("span", "blu-chip__label", p.Label));
+    if (p.IsRemovable) {
+      const b = node("button", "blu-chip__remove", "×");
+      b.type = "button";
+      b.disabled = !!p.IsDisabled;
+      b.setAttribute("aria-label", "Remove " + p.Label);
+      b.onclick = () => {
+        // Preserve the next useful keyboard stop before removing this chip.
+        const stops = Array.from(document.querySelectorAll<HTMLElement>('a[href],button:not(:disabled),input:not(:disabled),select:not(:disabled),textarea:not(:disabled),[tabindex="0"]')).filter(el => el.getClientRects().length && !r.contains(el));
+        const next = stops.find(el => !!(r.compareDocumentPosition(el) & Node.DOCUMENT_POSITION_FOLLOWING)) || stops.at(-1);
+        r.replaceChildren();
+        void events.Removed?.();
+        if (document.activeElement === document.body) next?.focus();
+      };
+      c.append(b);
+    }
+    r.replaceChildren(c);
+    if (focused) r.querySelector("button")?.focus();
+  });
+}
+
+export function createCard(host: HTMLElement, options: CardOptions) {
+  return component(host, options, (r, p) => {
+    const c = node(
+      "section",
+      classes(
+        "blu-card" + (p.IsBodyPadded === false ? " blu-card--flush" : ""),
+        p.ExtendedClass,
+      ),
+    );
+    if (p.Title || p.Description || p.Actions) {
+      const head = node("header", "blu-card__header"),
+        copy = node("div", "blu-card__heading");
+      if (p.Title)
+        copy.append(
+          node(
+            ("h" + (p.HeadingLevel || 2)) as "h2",
+            "blu-card__title",
+            p.Title,
+          ),
+        );
+      if (p.Description)
+        copy.append(node("span", "blu-card__description", p.Description));
+      head.append(copy);
+      if (p.Actions) {
+        const a = node("div", "blu-card__actions");
+        slot(a, p.Actions);
+        head.append(a);
+      }
+      c.append(head);
+    }
+    const body = node("div", "blu-card__body");
+    slot(body, p.Content);
+    c.append(body);
+    if (p.Footer) {
+      const f = node("footer", "blu-card__footer");
+      slot(f, p.Footer);
+      c.append(f);
+    }
+    r.replaceChildren(c);
+  });
+}
+
+export function createSkeleton(
+  host: HTMLElement,
+  options: SkeletonOptions = {},
+) {
+  return component(host, options, (r, p) => {
+    r.setAttribute("role", "status");
+    r.setAttribute("aria-label", p.AccessibleLabel || "Loading");
+    r.setAttribute("aria-busy", "true");
+    const n = node(
+      "div",
+      classes(
+        "blu-skeleton blu-skeleton--" +
+          (p.Shape || "Text").toLowerCase() +
+          (p.IsAnimated === false ? "" : " blu-skeleton--animated"),
+        p.ExtendedClass,
+      ),
+    );
+    n.setAttribute("aria-hidden", "true");
+    n.style.width = p.Width || "100%";
+    n.style.height = p.Height || "16px";
+    r.replaceChildren(n);
+  });
+}
+
+export function createChipGroup(host:HTMLElement,options:ChipGroupOptions={}) {
+ return component(host,options,(r,p)=>{r.className=classes("blu-chip-group",p.ExtendedClass);r.setAttribute("role","group");r.setAttribute("aria-label",p.AccessibleLabel||"Filters");if(p.Content!==undefined)r.replaceChildren(p.Content);});
+}
+export function createEmptyState(host:HTMLElement,options:EmptyStateOptions={},events:EmptyStateEvents={}) {
+ installEmptyState();
+ return bind(host,"EmptyState",options,()=>({Error:(message:string)=>events.Error?.(message)}),[],["Actions"]);
+}
+export type * from "./types.js";
+export { componentColors } from "./colors.js";

package/src/feedback.ts

@@ -0,0 +1,10 @@
+export * from './command-palette.js';
+export * from './modal.js';
+export * from './drawer.js';
+export * from './notification.js';
+export * from './tour.js';
+export * from './empty-state.js';
+export * from './notification-center.js';
+export * from './chat.js';
+export * from './chat-widget.js';
+export * from './float-button.js';

package/src/float-button.ts

@@ -0,0 +1,2 @@
+export * from './component-factories/float-button.js';
+export type * from './types.js';

package/src/font-provider.ts

@@ -0,0 +1,2 @@
+export * from './component-factories/font-provider.js';
+export type * from './types.js';

package/src/form-field.ts

@@ -0,0 +1,2 @@
+export {createFormField} from './form-layout/layout.js';
+export type * from './form-layout/types.js';

package/src/form-layout/choice.ts

@@ -0,0 +1,66 @@
+import { el, frame, lifecycle, common, attr, uid } from './shared.js';
+import type { CheckboxOptions, SwitchOptions, RadioButtonOptions, RadioGroupOptions, FieldComponent, FieldEvents } from './types.js';
+
+type ToggleOptions = CheckboxOptions & SwitchOptions;
+function toggle(host: HTMLElement, initial: ToggleOptions, events: FieldEvents<boolean>, kind: 'checkbox' | 'switch' | 'radio'): FieldComponent<ToggleOptions, boolean> {
+  let p = { ...initial }, initialized = false; const f = frame(host, p), label = el('label', 'blu-choice');
+  const input = el('input', 'blu-choice__input'), mark = el('span', 'blu-choice__mark'), text = el('span'), state = el('span', 'blu-choice__state');
+  input.type = kind === 'radio' ? 'radio' : 'checkbox'; if (kind === 'switch') input.setAttribute('role', 'switch');
+  label.classList.add('blu-choice--' + kind); mark.setAttribute('aria-hidden', 'true'); state.setAttribute('aria-hidden', 'true');
+  label.append(input, mark, text, state); f.body.append(label); const life = lifecycle(f.root, reset);
+  function update(patch: Partial<ToggleOptions>) {
+    life.check(); if (initialized && kind === 'radio' && !('Checked' in patch)) p.Checked = input.checked;
+    p = { ...p, ...patch }; f.paint(p, [input]); f.label.hidden = true;
+    // The wrapping label names this control. Safari also includes a hidden
+    // explicit label in its accessible name if that label keeps its `for`.
+    f.label.removeAttribute('for');
+    common(input, p); input.checked = !!p.Checked; input.indeterminate = kind === 'checkbox' && !!p.Indeterminate;
+    input.value = p.Value || 'on'; attr(input, 'aria-readonly', p.ReadOnly ? 'true' : undefined);
+    text.textContent = (p.Label || '') + (p.Required ? ' *' : ''); state.textContent = input.checked ? (p.OnText || '') : (p.OffText || ''); initialized = true;
+  }
+  function reset() { update({ Checked: !!initial.Checked, Indeterminate: !!initial.Indeterminate }); }
+  input.addEventListener('click', event => { if (p.ReadOnly) event.preventDefault(); }, { signal: life.signal });
+  input.addEventListener('keydown', event => { if (p.ReadOnly && ['ArrowLeft','ArrowRight','ArrowUp','ArrowDown',' '].includes(event.key)) event.preventDefault(); }, { signal: life.signal });
+  input.addEventListener('change', () => { p.Checked = input.checked; p.Indeterminate = false; state.textContent = input.checked ? (p.OnText || '') : (p.OffText || ''); events.Change?.(input.checked); }, { signal: life.signal });
+  input.addEventListener('blur', () => events.Blur?.(), { signal: life.signal }); update({});
+  return { element: f.root, control: input, update, reset, getValue: () => input.checked, focus: () => input.focus(), validate: () => input.reportValidity(), destroy: life.destroy };
+}
+export function createCheckbox(host: HTMLElement, options: CheckboxOptions = {}, events: FieldEvents<boolean> = {}) { return toggle(host, options, events, 'checkbox'); }
+export function createSwitch(host: HTMLElement, options: SwitchOptions = {}, events: FieldEvents<boolean> = {}) { return toggle(host, options, events, 'switch'); }
+export function createRadioButton(host: HTMLElement, options: RadioButtonOptions, events: FieldEvents<boolean> = {}) { return toggle(host, options, events, 'radio'); }
+
+export function createRadioGroup(host: HTMLElement, initial: RadioGroupOptions, events: FieldEvents<string> = {}) {
+  let p = { ...initial }, controls: HTMLInputElement[] = [];
+  const f = frame(host, p, true), name = p.Name || uid(); const life = lifecycle(f.root, reset);
+  function update(patch: Partial<RadioGroupOptions>) {
+    life.check(); const replace = !controls.length || 'Options' in patch; p = { ...p, ...patch };
+    if (new Set(p.Options.map(o => o.Value)).size !== p.Options.length) throw Error('Radio option values must be unique.');
+    f.body.className = 'blu-radio-group blu-radio-group--' + (p.Direction || 'Vertical').toLowerCase();
+    if (replace) {
+      f.body.replaceChildren(); controls = p.Options.map((option, i) => {
+        const label = el('label', 'blu-choice blu-choice--radio'), input = el('input', 'blu-choice__input'), mark = el('span', 'blu-choice__mark'), copy = el('span');
+        input.type = 'radio'; input.id = f.id + '-' + i; input.value = option.Value; mark.setAttribute('aria-hidden', 'true');
+        const title = el('span', '', option.Label); title.id = input.id + '-label'; copy.append(title);
+        // Keep the option's name separate from its description so screen
+        // readers do not announce the description twice via the wrapping label.
+        input.setAttribute('aria-labelledby', title.id);
+        if (option.Description) { const desc = el('small', 'blu-choice__description', option.Description); desc.id = input.id + '-description'; copy.append(desc); }
+        label.append(input, mark, copy); f.body.append(label);
+        input.onchange = () => { if (input.checked) { p.Value = input.value; events.Change?.(input.value); } };
+        input.onclick = event => { if (p.ReadOnly) event.preventDefault(); };
+        input.onkeydown = event => { if (p.ReadOnly && ['ArrowLeft','ArrowRight','ArrowUp','ArrowDown',' '].includes(event.key)) event.preventDefault(); };
+        input.onblur = () => events.Blur?.(); return input;
+      });
+    }
+    f.paint(p, controls);
+    controls.forEach((input, i) => {
+      common(input, p); input.name = p.Name || name; input.disabled = !!p.Disabled || !!p.Options[i].Disabled; input.checked = input.value === p.Value;
+      attr(input, 'aria-readonly', p.ReadOnly ? 'true' : undefined);
+      if (p.Options[i].Description) attr(input, 'aria-describedby', [input.getAttribute('aria-describedby'), input.id + '-description'].filter(Boolean).join(' '));
+    });
+  }
+  function reset() { update({ Value: initial.Value || '' }); } update({});
+  return { element: f.root, update, reset, getValue: () => controls.find(c => c.checked)?.value || '',
+    focus: () => (controls.find(c => c.checked && !c.disabled) || controls.find(c => !c.disabled))?.focus(),
+    validate: () => controls.filter(c => !c.disabled).every(c => c.reportValidity()), destroy: life.destroy };
+}

package/src/form-layout/layout.ts

@@ -0,0 +1,40 @@
+import { el, frame, bound } from './shared.js';
+import type { FormFieldOptions, ColumnsOptions, ColumnsComponent } from './types.js';
+
+/** Wrap a consumer-owned control. Destroy restores its original ARIA attributes. */
+export function createFormField(host: HTMLElement, initial: FormFieldOptions = {}) {
+  let p = { ...initial }, disposed = false, current: HTMLElement | undefined;
+  let original: Record<string, string | null> = {};
+  const f = frame(host, p), content = f.body;
+  const attributes = ['id', 'aria-describedby', 'aria-invalid', 'aria-required'];
+  function restore() { if (current) for (const name of attributes) { const value = original[name]; if (value === null) current.removeAttribute(name); else current.setAttribute(name, value); } }
+  function update(patch: Partial<FormFieldOptions>) {
+    if (disposed) throw Error('Component is destroyed.'); p = { ...p, ...patch };
+    if (p.Control !== current) {
+      restore(); content.replaceChildren(); current = p.Control;
+      if (current) { original = Object.fromEntries(attributes.map(name => [name, current!.getAttribute(name)])); content.append(current); }
+    }
+    f.paint(p, current ? [current] : []);
+    if (current && original['aria-describedby']) current.setAttribute('aria-describedby', [original['aria-describedby'], current.getAttribute('aria-describedby')].filter(Boolean).join(' '));
+  }
+  update({}); return { element: f.root, content, update, destroy() { if (disposed) return; disposed = true; restore(); f.root.remove(); } };
+}
+
+export function createColumns(host: HTMLElement, count: 2 | 3 | 4, initial: ColumnsOptions = {}): ColumnsComponent {
+  let p = { ...initial }, disposed = false; const root = el('div', 'blu-columns');
+  const columns = Array.from({ length: count }, (_, i) => { const column = el('div', 'blu-columns__column'); column.dataset.column = String(i + 1); root.append(column); return column; }); host.append(root);
+  function update(patch: Partial<ColumnsOptions>) {
+    if (disposed) throw Error('Component is destroyed.'); p = { ...p, ...patch };
+    const pairs: Record<string, string> = { Equal: 'minmax(0,1fr) minmax(0,1fr)', OneThirdTwoThirds: 'minmax(0,1fr) minmax(0,2fr)', TwoThirdsOneThird: 'minmax(0,2fr) minmax(0,1fr)', OneQuarterThreeQuarters: 'minmax(0,1fr) minmax(0,3fr)', ThreeQuartersOneQuarter: 'minmax(0,3fr) minmax(0,1fr)' };
+    if (count === 2 && p.Ratio && !pairs[p.Ratio]) throw Error('Unsupported two-column ratio.');
+    if (count === 3 && p.Ratio && !['Equal', 'WideCenter'].includes(p.Ratio)) throw Error('Unsupported three-column ratio.');
+    if (count === 4 && p.Ratio && p.Ratio !== 'Equal') throw Error('Four columns use equal widths.');
+    root.className = 'blu-columns blu-columns--stack-' + (p.StackAt || 'Medium').toLowerCase() + (p.EqualHeight ? ' blu-columns--equal-height' : '') + (p.ExtendedClass ? ' ' + p.ExtendedClass : '');
+    root.style.setProperty('--blu-columns-tracks', count === 2 ? pairs[p.Ratio || 'Equal'] : count === 3 && p.Ratio === 'WideCenter' ? 'minmax(0,1fr) minmax(0,2fr) minmax(0,1fr)' : `repeat(${count}, minmax(0, 1fr))`);
+    root.style.setProperty('--blu-columns-gap', bound(p.Gap, 24, 0, 96) + 'px'); root.style.alignItems = p.EqualHeight ? 'stretch' : (p.Align || 'Stretch').toLowerCase();
+  }
+  update({}); return { element: root, columns, update, destroy() { if (disposed) return; disposed = true; root.remove(); } };
+}
+export const createColumns2 = (host: HTMLElement, options: ColumnsOptions = {}) => createColumns(host, 2, options);
+export const createColumns3 = (host: HTMLElement, options: ColumnsOptions = {}) => createColumns(host, 3, options);
+export const createColumns4 = (host: HTMLElement, options: ColumnsOptions = {}) => createColumns(host, 4, options);