@blukavantui/community 0.0.0-stage → 1.0.1

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,9 @@
+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';

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/grid-basic.ts

@@ -0,0 +1,46 @@
+/** BluGrid Basic — a deliberately small, read-only Community adapter. */
+import {createGrid,themeQuartz,ClientSideRowModelModule,TextFilterModule,NumberFilterModule,DateFilterModule,RenderApiModule,PaginationModule,RowSelectionModule,ColumnAutoSizeModule,CellStyleModule,type ColDef,type GridApi} from 'ag-grid-community';
+import {normalizeOptions,formatValue,parseDate,type Row,type GridBasicOptions,type GridBasicEvents,type NormalizedOptions} from './grid-spec.js';
+export type {BasicColumn,ColumnType,Row,GridBasicOptions,GridBasicEvents} from './grid-spec.js';
+export interface GridBasic {
+ readonly element:HTMLElement;
+ /** Validated input update. The underlying grid API is intentionally private. */
+ update(patch:Partial<GridBasicOptions>):void;
+ clearSelection():void;
+ destroy():void;
+}
+const modules=[ClientSideRowModelModule,TextFilterModule,NumberFilterModule,DateFilterModule,RenderApiModule,PaginationModule,RowSelectionModule,ColumnAutoSizeModule,CellStyleModule];
+const theme=themeQuartz.withParams({accentColor:'var(--bluui-primary, #5144ed)',backgroundColor:'var(--bluui-surface, #fff)',foregroundColor:'var(--bluui-text, #182333)',borderColor:'var(--bluui-border, #dce3ed)',headerBackgroundColor:'var(--bluui-surface-muted, #f4f6fa)',headerTextColor:'var(--bluui-text-muted, #68758b)',rowHoverColor:'var(--bluui-surface-muted, #f4f6fa)',selectedRowBackgroundColor:'var(--bluui-primary-soft, #edeaff)',fontFamily:'var(--blu-font-family, system-ui)',fontSize:14,headerFontSize:12,headerFontWeight:600,rowHeight:44,headerHeight:44,wrapperBorderRadius:12,browserColorScheme:'inherit'});
+const copy=(r:Row|undefined)=>r?{...r}:null;
+function columns(p:NormalizedOptions):ColDef<Row>[] {
+ return p.Columns.map(c=>{const type=c.Type||'Text';const isDate=type==='Date'||type==='DateTime';return {
+  field:c.Field,colId:c.Field,headerName:c.Header??c.Field,minWidth:c.MinWidth||100,width:c.Width,flex:c.Width?undefined:1,
+  sortable:c.IsSortable!==false,filter:c.IsFilterable===false?false:(isDate?'agDateColumnFilter':type==='Number'||type==='Currency'?'agNumberColumnFilter':'agTextColumnFilter'),
+  editable:false,cellDataType:false,suppressMovable:true,lockPinned:true,
+  valueFormatter:({value})=>formatValue(value,type,p),
+  filterValueGetter:({data})=>isDate?parseDate(data?.[c.Field],type==='DateTime'):type==='Boolean'?formatValue(data?.[c.Field],type,p):data?.[c.Field],
+  filterParams:{maxNumConditions:1,...(isDate?{comparator:(local:Date,v:unknown)=>{if(!(v instanceof Date))return -1;const parts=new Intl.DateTimeFormat('en-CA',{timeZone:type==='Date'?'UTC':p.TimeZone,year:'numeric',month:'2-digit',day:'2-digit'}).formatToParts(v);const val=(k:string)=>Number(parts.find(x=>x.type===k)?.value);const t=new Date(val('year'),val('month')-1,val('day')).getTime();return Math.sign(t-local.getTime());}}:{})},
+  cellClass:type==='Number'||type==='Currency'?'blu-grid-basic__number':undefined,
+ };});
+}
+export function createGridBasic(host:HTMLElement,input:GridBasicOptions,events:GridBasicEvents={}):GridBasic {
+ let p=normalizeOptions(input),disposed=false,api:GridApi<Row>;
+ if(!host.isConnected)throw Error('Mount BluGrid Basic into a connected element.');
+ const root=document.createElement('div');host.append(root);
+ const appearance=()=>{root.className='blu-grid-basic'+(p.ExtendedClass?' '+p.ExtendedClass:'');root.style.height=p.Height;};appearance();
+ try { api=createGrid<Row>(root,{
+  theme,rowData:p.Rows,columnDefs:columns(p),getRowId:({data})=>String(data[p.RowKeyField]),
+  rowModelType:'clientSide',pagination:p.EnablePagination,paginationPageSize:p.PageSize,paginationPageSizeSelector:false,
+  rowSelection:p.EnableSelection?{mode:'singleRow',enableClickSelection:true,checkboxes:false}:undefined,
+  suppressMultiSort:true,suppressMovableColumns:true,animateRows:false,ensureDomOrder:true,
+  defaultColDef:{resizable:true,editable:false},enableCellTextSelection:true,
+  onGridReady:()=>events.Ready?.(),onRowClicked:e=>{if(e.data)events.RowClicked?.({...e.data});},
+  onSelectionChanged:e=>events.SelectionChanged?.(copy(e.api.getSelectedRows()[0])),
+ },{modules});api.setGridAriaProperty('label',p.AccessibleLabel);
+ }catch(error){root.remove();throw error;}
+ return {element:root,update(patch){if(disposed)throw Error('Grid is destroyed.');const next=normalizeOptions({...p,...patch});if(next.RowKeyField!==p.RowKeyField)throw Error('RowKeyField cannot change after initialization.');const changeColumns=JSON.stringify(next.Columns)!==JSON.stringify(p.Columns)||next.Locale!==p.Locale||next.Currency!==p.Currency||next.TimeZone!==p.TimeZone;
+  const selectionChanged=next.EnableSelection!==p.EnableSelection;p=next;appearance();
+  api.updateGridOptions({rowData:p.Rows,...(changeColumns?{columnDefs:columns(p)}:{}),pagination:p.EnablePagination,paginationPageSize:p.PageSize,...(selectionChanged?{rowSelection:p.EnableSelection?{mode:'singleRow' as const,enableClickSelection:true,checkboxes:false}:undefined}:{})});
+  if(selectionChanged&&!p.EnableSelection)api.deselectAll();api.setGridAriaProperty('label',p.AccessibleLabel);
+ },clearSelection(){if(!disposed)api.deselectAll();},destroy(){if(disposed)return;disposed=true;api.destroy();root.remove();}};
+}

package/src/grid-spec.ts

@@ -0,0 +1,93 @@
+/** Closed, read-only contract. No AG Grid options or engine API escape hatch. */
+export type Row = Record<string, string | number | boolean | null>;
+export type ColumnType = 'Text' | 'Number' | 'Currency' | 'Date' | 'DateTime' | 'Boolean';
+export interface BasicColumn {
+  Field: string;
+  Header?: string;
+  Type?: ColumnType;
+  Width?: number;
+  MinWidth?: number;
+  IsSortable?: boolean;
+  IsFilterable?: boolean;
+}
+export interface GridBasicOptions {
+  Columns: BasicColumn[];
+  Rows: Row[];
+  RowKeyField?: string;
+  Height?: string;
+  PageSize?: number;
+  EnablePagination?: boolean;
+  EnableSelection?: boolean;
+  Locale?: string;
+  Currency?: string;
+  TimeZone?: string;
+  AccessibleLabel?: string;
+  ExtendedClass?: string;
+}
+export interface GridBasicEvents {
+  Ready?: () => void;
+  RowClicked?: (row: Row) => void;
+  SelectionChanged?: (row: Row | null) => void;
+  Error?: (message: string) => void;
+}
+export type NormalizedOptions = Required<GridBasicOptions>;
+const blocked = new Set(['__proto__', 'prototype', 'constructor']);
+function record(value: unknown): value is Record<string,unknown> {
+  return !!value && typeof value === 'object' && !Array.isArray(value) && [Object.prototype,null].includes(Object.getPrototypeOf(value));
+}
+function fields(value: Record<string,unknown>, allowed: readonly string[], scope: string) {
+  for (const key of Object.keys(value)) if (!allowed.includes(key) || blocked.has(key)) throw Error(`${scope}: unsupported property ${key}.`);
+}
+function text(value: unknown, label: string, empty = false): asserts value is string {
+  if (typeof value !== 'string' || (!empty && !value.trim())) throw Error(`${label} must be text${empty?'':' and nonempty'}.`);
+}
+function boolean(value:unknown,label:string) { if(typeof value !== 'boolean') throw Error(`${label} must be Boolean.`); }
+const optionKeys = ['Columns','Rows','RowKeyField','Height','PageSize','EnablePagination','EnableSelection','Locale','Currency','TimeZone','AccessibleLabel','ExtendedClass'];
+const columnKeys = ['Field','Header','Type','Width','MinWidth','IsSortable','IsFilterable'];
+export function normalizeOptions(input:GridBasicOptions):NormalizedOptions {
+  if(!record(input)) throw Error('Grid options must be an object.');
+  fields(input,optionKeys,'Grid');
+  const p:NormalizedOptions = {RowKeyField:'Id',Height:'480px',PageSize:25,EnablePagination:true,EnableSelection:true,Locale:'en-US',Currency:'USD',TimeZone:'UTC',AccessibleLabel:'Data table',ExtendedClass:'',...input};
+  for(const key of ['RowKeyField','Height','Locale','Currency','TimeZone','AccessibleLabel'] as const)text(p[key],key);
+  text(p.ExtendedClass,'ExtendedClass',true);
+  if(blocked.has(p.RowKeyField))throw Error('Invalid RowKeyField.');
+  if(!/^\d+(\.\d+)?(px|rem|vh|dvh|%)$/.test(p.Height))throw Error('Height must be a nonnegative CSS length (px, rem, vh, dvh or %).');
+  if(!Number.isSafeInteger(p.PageSize)||p.PageSize<1||p.PageSize>10000)throw Error('PageSize must be an integer from 1 to 10000.');
+  boolean(p.EnablePagination,'EnablePagination');boolean(p.EnableSelection,'EnableSelection');
+  new Intl.NumberFormat(p.Locale,{style:'currency',currency:p.Currency});
+  new Intl.DateTimeFormat(p.Locale,{timeZone:p.TimeZone});
+  if(!Array.isArray(p.Columns)||!p.Columns.length)throw Error('Columns must contain at least one column.');
+  const seen=new Set<string>();
+  p.Columns=p.Columns.map(c=>{
+    if(!record(c))throw Error('Each column must be an object.');fields(c,columnKeys,'Column');text(c.Field,'Column.Field');
+    if(blocked.has(c.Field)||seen.has(c.Field))throw Error('Column fields must be unique and safe.');seen.add(c.Field);
+    if(c.Header!==undefined)text(c.Header,'Column.Header',true);
+    if(c.Type!==undefined&&!['Text','Number','Currency','Date','DateTime','Boolean'].includes(c.Type))throw Error('Invalid column Type.');
+    for(const k of ['Width','MinWidth'] as const)if(c[k]!==undefined&&(!Number.isFinite(c[k])||c[k]!<40||c[k]!>4000))throw Error(`${k} must be from 40 to 4000.`);
+    for(const k of ['IsSortable','IsFilterable'] as const)if(c[k]!==undefined)boolean(c[k],k);
+    return {...c};
+  });
+  if(!Array.isArray(p.Rows))throw Error('Rows must be a list.');
+  const ids=new Set<string>();
+  p.Rows=p.Rows.map(r=>{
+    if(!record(r))throw Error('Every row must be an object.');
+    for(const [k,v]of Object.entries(r))if(blocked.has(k)||!(v===null||typeof v==='string'||typeof v==='boolean'||(typeof v==='number'&&Number.isFinite(v))))throw Error(`Invalid value in row field ${k}.`);
+    const id=r[p.RowKeyField];if(!['string','number'].includes(typeof id)||String(id)===''||ids.has(String(id)))throw Error('Rows need unique, nonempty keys in RowKeyField.');ids.add(String(id));
+    return {...r};
+  });
+  return p;
+}
+/** Date-only values never shift across zones. Invalid values display as blank. */
+export function parseDate(value:unknown,instant=false):Date|null {
+  if(typeof value!=='string'||!value)return null;
+  if(!instant){if(!/^\d{4}-\d{2}-\d{2}$/.test(value))return null;const d=new Date(value+'T00:00:00Z');return Number.isFinite(d.getTime())&&d.toISOString().slice(0,10)===value?d:null;}
+  if(!/^\d{4}-\d{2}-\d{2}T.*(?:Z|[+-]\d{2}:\d{2})$/.test(value))return null;
+  const d=new Date(value);return Number.isFinite(d.getTime())?d:null;
+}
+export function formatValue(value:unknown,type:ColumnType,p:NormalizedOptions):string {
+  if(value===null||value===undefined)return '';
+  if(type==='Boolean')return value===true?'Yes':value===false?'No':'';
+  if(type==='Number'||type==='Currency')return typeof value==='number'&&Number.isFinite(value)?new Intl.NumberFormat(p.Locale,type==='Currency'?{style:'currency',currency:p.Currency}:{}).format(value):'';
+  if(type==='Date'||type==='DateTime'){const d=parseDate(value,type==='DateTime');return d?new Intl.DateTimeFormat(p.Locale,{dateStyle:'medium',...(type==='DateTime'?{timeStyle:'short',timeZone:p.TimeZone}:{timeZone:'UTC'})}).format(d):'';}
+  return String(value);
+}

package/src/grid.ts

@@ -0,0 +1 @@
+export * from './grid-basic.js';

package/src/hero-section.ts

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

package/src/image-compare.ts

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