@sondor-technology/sondor-components 1.0.9 → 1.0.10

package/src/components/table/data-table.utils.ts

@@ -0,0 +1,276 @@
+/**
+ * Pure data helpers for st-data-table (search, filter, sort, paginate). They have no DOM or Lit
+ * dependencies so they can be unit tested and reused for server-side logic.
+ */
+
+export type FilterType = "text" | "number" | "select" | "boolean";
+export type SortDirection = "asc" | "desc";
+
+export type FilterOperator =
+  | "contains"
+  | "notContains"
+  | "equals"
+  | "startsWith"
+  | "endsWith"
+  | "eq"
+  | "neq"
+  | "gt"
+  | "gte"
+  | "lt"
+  | "lte"
+  | "is"
+  | "isNot"
+  | "isTrue"
+  | "isFalse";
+
+export interface FilterOption {
+  label: string;
+  value: string;
+}
+
+export interface DataTableColumn {
+  header: string;
+  key: string;
+  /** Click the header to sort. Shift+click adds the column to a multi-column sort. */
+  sortable?: boolean;
+  hidden?: boolean;
+  /** Adds the column to the filter builder with this value type. */
+  filter?: FilterType;
+  /** Choices for `select` filters. Derived from the data when omitted. */
+  options?: FilterOption[];
+  /** Set to false to exclude the column from the search box. */
+  searchable?: boolean;
+  align?: "start" | "center" | "end";
+  /** Any CSS width, e.g. "8rem". */
+  width?: string;
+  /** Underlying value used for search, filter and sort when it differs from `row[key]`. */
+  value?: (row: any) => unknown;
+  /** Custom cell content (JavaScript only). */
+  render?: (row: any) => unknown;
+}
+
+export interface SortConfig {
+  key: string;
+  direction: SortDirection;
+}
+
+export interface DataFilter {
+  key: string;
+  op: FilterOperator;
+  value?: string;
+}
+
+export interface OperatorInfo {
+  op: FilterOperator;
+  label: string;
+  /** False for operators that take no value, such as `isTrue`. */
+  needsValue: boolean;
+}
+
+const OPERATORS: Record<FilterType, OperatorInfo[]> = {
+  text: [
+    {op: "contains", label: "contains", needsValue: true},
+    {op: "notContains", label: "does not contain", needsValue: true},
+    {op: "equals", label: "equals", needsValue: true},
+    {op: "startsWith", label: "starts with", needsValue: true},
+    {op: "endsWith", label: "ends with", needsValue: true},
+  ],
+  number: [
+    {op: "eq", label: "=", needsValue: true},
+    {op: "neq", label: "≠", needsValue: true},
+    {op: "gt", label: ">", needsValue: true},
+    {op: "gte", label: "≥", needsValue: true},
+    {op: "lt", label: "<", needsValue: true},
+    {op: "lte", label: "≤", needsValue: true},
+  ],
+  select: [
+    {op: "is", label: "is", needsValue: true},
+    {op: "isNot", label: "is not", needsValue: true},
+  ],
+  boolean: [
+    {op: "isTrue", label: "is yes", needsValue: false},
+    {op: "isFalse", label: "is no", needsValue: false},
+  ],
+};
+
+export const operatorsFor = (type: FilterType): OperatorInfo[] => OPERATORS[type];
+
+export const defaultOperator = (type: FilterType): FilterOperator => OPERATORS[type][0].op;
+
+const operatorInfo = (type: FilterType, op: FilterOperator) =>
+  OPERATORS[type].find((o) => o.op === op);
+
+/** Reads the comparable value for a column: its `value` accessor, else `row[key]`. */
+export const cellValue = (row: any, column: Pick<DataTableColumn, "key" | "value">): unknown =>
+  column.value ? column.value(row) : row?.[column.key];
+
+const isBlank = (v: unknown) => v === null || v === undefined || v === "";
+
+const toText = (v: unknown) => (v === null || v === undefined ? "" : String(v)).toLowerCase();
+
+/** A filter is applied only once it has everything it needs (e.g. a value for "contains"). */
+export function isFilterComplete(filter: DataFilter, columns: DataTableColumn[]): boolean {
+  const column = columns.find((c) => c.key === filter.key);
+  if (!column?.filter) return false;
+  const info = operatorInfo(column.filter, filter.op);
+  if (!info) return false;
+  return !info.needsValue || (filter.value ?? "").trim() !== "";
+}
+
+function matches(filter: DataFilter, type: FilterType, raw: unknown): boolean {
+  const value = (filter.value ?? "").trim();
+  switch (type) {
+    case "text": {
+      const cell = toText(raw);
+      const needle = value.toLowerCase();
+      if (filter.op === "contains") return cell.includes(needle);
+      if (filter.op === "notContains") return !cell.includes(needle);
+      if (filter.op === "equals") return cell === needle;
+      if (filter.op === "startsWith") return cell.startsWith(needle);
+      if (filter.op === "endsWith") return cell.endsWith(needle);
+      return true;
+    }
+    case "number": {
+      if (isBlank(raw)) return false;
+      const cell = Number(raw);
+      const target = Number(value);
+      if (Number.isNaN(cell) || Number.isNaN(target)) return false;
+      if (filter.op === "eq") return cell === target;
+      if (filter.op === "neq") return cell !== target;
+      if (filter.op === "gt") return cell > target;
+      if (filter.op === "gte") return cell >= target;
+      if (filter.op === "lt") return cell < target;
+      if (filter.op === "lte") return cell <= target;
+      return true;
+    }
+    case "select": {
+      const same = String(raw ?? "") === value;
+      return filter.op === "isNot" ? !same : same;
+    }
+    case "boolean": {
+      const truthy = raw === true || toText(raw) === "true" || toText(raw) === "yes";
+      return filter.op === "isFalse" ? !truthy : truthy;
+    }
+  }
+}
+
+/** Keeps rows that satisfy every complete filter (AND), across any number of columns. */
+export function applyFilters<T>(rows: T[], filters: DataFilter[], columns: DataTableColumn[]): T[] {
+  const active = filters.filter((f) => isFilterComplete(f, columns));
+  if (!active.length) return rows;
+  const byKey = new Map(columns.map((c) => [c.key, c]));
+  return rows.filter((row) =>
+    active.every((f) => {
+      const column = byKey.get(f.key)!;
+      return matches(f, column.filter!, cellValue(row, column));
+    }),
+  );
+}
+
+/** Every whitespace separated term must appear in at least one searchable column. */
+export function searchRows<T>(rows: T[], query: string, columns: DataTableColumn[]): T[] {
+  const terms = query.toLowerCase().split(/\s+/).filter(Boolean);
+  if (!terms.length) return rows;
+  const searchable = columns.filter((c) => c.searchable !== false);
+  return rows.filter((row) => {
+    const haystack = searchable.map((c) => toText(cellValue(row, c)));
+    return terms.every((term) => haystack.some((cell) => cell.includes(term)));
+  });
+}
+
+const collator = new Intl.Collator(undefined, {numeric: true, sensitivity: "base"});
+
+/** Compares two cell values: numbers numerically, dates by time, everything else naturally. */
+export function compareValues(a: unknown, b: unknown): number {
+  if (a instanceof Date && b instanceof Date) return a.getTime() - b.getTime();
+  if (typeof a === "number" && typeof b === "number") return a - b;
+  if (typeof a === "boolean" && typeof b === "boolean") return Number(a) - Number(b);
+  return collator.compare(String(a), String(b));
+}
+
+/** Stable multi-column sort. Empty values always sort last, whichever the direction. */
+export function sortRows<T>(rows: T[], sorts: SortConfig[], columns: DataTableColumn[]): T[] {
+  const active = sorts.filter((s) => columns.some((c) => c.key === s.key));
+  if (!active.length) return rows;
+  const byKey = new Map(columns.map((c) => [c.key, c]));
+  return rows
+    .map((row, index) => ({row, index}))
+    .sort((x, y) => {
+      for (const s of active) {
+        const column = byKey.get(s.key)!;
+        const a = cellValue(x.row, column);
+        const b = cellValue(y.row, column);
+        const aBlank = isBlank(a);
+        const bBlank = isBlank(b);
+        if (aBlank || bBlank) {
+          if (aBlank && bBlank) continue;
+          return aBlank ? 1 : -1;
+        }
+        const result = compareValues(a, b);
+        if (result !== 0) return s.direction === "asc" ? result : -result;
+      }
+      return x.index - y.index;
+    })
+    .map(({row}) => row);
+}
+
+/**
+ * Advances a column through none -> asc -> desc -> none. With `additive` (Shift+click) other
+ * sorted columns are kept so users can sort by several columns; otherwise they are replaced.
+ */
+export function nextSort(current: SortConfig[], key: string, additive: boolean): SortConfig[] {
+  const existing = current.find((s) => s.key === key);
+  const direction: SortDirection | null = !existing ? "asc" : existing.direction === "asc" ? "desc" : null;
+  const others = additive ? current.filter((s) => s.key !== key) : [];
+  if (!direction) return additive ? current.filter((s) => s.key !== key) : [];
+  if (additive && existing) return current.map((s) => (s.key === key ? {key, direction} : s));
+  return [...others, {key, direction}];
+}
+
+export interface PageSlice<T> {
+  rows: T[];
+  page: number;
+  totalPages: number;
+  total: number;
+  /** 1-based index of the first and last row on the page (0 when empty). */
+  from: number;
+  to: number;
+}
+
+/** Slices one page and clamps `page` into range. */
+export function paginate<T>(rows: T[], page: number, pageSize: number): PageSlice<T> {
+  const size = Math.max(1, pageSize);
+  const totalPages = Math.max(1, Math.ceil(rows.length / size));
+  const current = Math.min(Math.max(1, page), totalPages);
+  const start = (current - 1) * size;
+  const slice = rows.slice(start, start + size);
+  return {
+    rows: slice,
+    page: current,
+    totalPages,
+    total: rows.length,
+    from: slice.length ? start + 1 : 0,
+    to: start + slice.length,
+  };
+}
+
+/** Distinct values of a column, as options for a select filter. */
+export function deriveOptions(rows: any[], column: DataTableColumn): FilterOption[] {
+  const seen = new Set<string>();
+  for (const row of rows) {
+    const v = cellValue(row, column);
+    if (!isBlank(v)) seen.add(String(v));
+  }
+  return [...seen].sort(collator.compare).map((value) => ({label: value, value}));
+}
+
+/** Human readable summary of a filter, e.g. "Status is Active". */
+export function describeFilter(filter: DataFilter, columns: DataTableColumn[]): string {
+  const column = columns.find((c) => c.key === filter.key);
+  if (!column?.filter) return filter.key;
+  const info = operatorInfo(column.filter, filter.op);
+  const value = column.filter === "select"
+    ? (column.options?.find((o) => o.value === filter.value)?.label ?? filter.value ?? "")
+    : (filter.value ?? "");
+  return [column.header, info?.label ?? filter.op, info?.needsValue ? value : ""].filter(Boolean).join(" ");
+}

package/src/components/table/table.ts

@@ -1,14 +1,31 @@
-import {LitElement, html, css} from "lit";
+import {LitElement, html, css, nothing} from "lit";
 import {customElement, property} from "lit/decorators.js";
+import {classMap} from "lit/directives/class-map.js";
+import {ifDefined} from "lit/directives/if-defined.js";
 import {resetStyles} from "../../styles/reset.js";
+import "../skeleton/skeleton.js";
 
 export type TableMode = "horizontal" | "vertical";
+export type TableAlign = "start" | "center" | "end";
 
 export interface TableColumn {
   header: string;
   key: string;
+  /** Horizontal alignment of the column. Numbers usually read best with "end". */
+  align?: TableAlign;
+  /** Any CSS width, e.g. "8rem" or "20%". */
+  width?: string;
+  /** Custom cell content (JavaScript only). Return text or a Lit template. */
+  render?: (row: Record<string, any>, index: number) => unknown;
 }
 
+const SKELETON_ROWS = 3;
+
+/**
+ * Lightweight data table. Use `st-data-table` when you need sorting, search or pagination.
+ *
+ * Events: `st-row-click` (detail: the row object) when `clickable-rows` is set.
+ */
 @customElement("st-table")
 export class StTable extends LitElement {
   @property({type: Array}) columns: TableColumn[] = [];
@@ -18,6 +35,17 @@ export class StTable extends LitElement {
   @property({type: Boolean, reflect: true}) striped = false;
   @property({type: Boolean, reflect: true}) hoverable = false;
   @property({type: Boolean, reflect: true}) dense = false;
+  /** Keeps the header visible while the body scrolls. Set a height with `--st-table-max-height`. */
+  @property({type: Boolean, reflect: true, attribute: "sticky-header"}) stickyHeader = false;
+  /** Shows placeholder rows and sets `aria-busy`. */
+  @property({type: Boolean, reflect: true}) loading = false;
+  /** Makes rows focusable and emits `st-row-click` on click, Enter or Space. */
+  @property({type: Boolean, reflect: true, attribute: "clickable-rows"}) clickableRows = false;
+
+  /** Describes the table to assistive technology (and visually, unless `caption-hidden`). */
+  @property({type: String}) caption = "";
+  @property({type: Boolean, reflect: true, attribute: "caption-hidden"}) captionHidden = false;
+  @property({type: String, attribute: "empty-text"}) emptyText = "No data available.";
 
   static styles = [
     resetStyles,
@@ -29,20 +57,40 @@ export class StTable extends LitElement {
 
       .table-wrapper {
         width: 100%;
-        overflow-x: auto;
+        overflow: auto;
         -webkit-overflow-scrolling: touch;
+        max-height: var(--st-table-max-height, none);
       }
 
       table {
         width: 100%;
         border-collapse: collapse;
         text-align: left;
-        font-size: var(--st-font-size-base, 1rem);
+        font-size: var(--st-font-size-base);
+        color: var(--st-color-text);
+      }
+
+      caption {
+        padding: var(--st-spacing-sm) var(--st-spacing-lg);
+        text-align: left;
+        font-weight: var(--st-font-weight-medium);
         color: var(--st-color-text);
       }
 
+      :host([caption-hidden]) caption {
+        position: absolute;
+        width: 1px;
+        height: 1px;
+        padding: 0;
+        margin: -1px;
+        overflow: hidden;
+        clip: rect(0, 0, 0, 0);
+        white-space: nowrap;
+        border: 0;
+      }
+
       th {
-        font-weight: 600;
+        font-weight: var(--st-font-weight-semibold);
         padding: var(--st-spacing-md) var(--st-spacing-lg);
         border-bottom: 2px solid var(--st-color-border);
         color: var(--st-color-text-muted);
@@ -54,18 +102,42 @@ export class StTable extends LitElement {
         border-bottom: 1px solid var(--st-color-border);
       }
 
+      .align-center {
+        text-align: center;
+      }
+      .align-end {
+        text-align: end;
+      }
+
       /* Modifiers */
       :host([dense]) th,
       :host([dense]) td {
         padding: var(--st-spacing-sm) var(--st-spacing-md);
       }
 
+      :host([sticky-header]) th {
+        position: sticky;
+        top: 0;
+        z-index: 1;
+        background-color: var(--st-color-bg);
+      }
+
       :host([striped]) tbody tr:nth-of-type(odd) {
-        background-color: var(--st-color-surface-muted, #f8fafc);
+        background-color: var(--st-color-surface-muted);
+      }
+
+      :host([hoverable]) tbody tr:hover,
+      tbody tr.clickable:hover {
+        background-color: var(--st-color-surface-hover);
       }
 
-      :host([hoverable]) tbody tr:hover {
-        background-color: var(--st-color-surface-hover, #f1f5f9);
+      tbody tr.clickable {
+        cursor: pointer;
+      }
+
+      tbody tr.clickable:focus-visible {
+        outline: 2px solid var(--st-color-primary);
+        outline-offset: -2px;
       }
 
       /* ==========================================================
@@ -115,7 +187,7 @@ export class StTable extends LitElement {
       /* Inject the header name on the left */
       :host([mode="vertical"]) td::before {
         content: attr(data-label);
-        font-weight: 600;
+        font-weight: var(--st-font-weight-semibold);
         text-align: left;
         padding-right: var(--st-spacing-md);
         color: var(--st-color-text-muted);
@@ -123,46 +195,104 @@ export class StTable extends LitElement {
 
       .empty-state {
         text-align: center;
-        padding: 2rem !important;
+        padding: var(--st-spacing-xl) !important;
         color: var(--st-color-text-muted);
         font-style: italic;
       }
     `,
   ];
 
+  private _alignClass(col: TableColumn) {
+    return classMap({"align-center": col.align === "center", "align-end": col.align === "end"});
+  }
+
+  private _onRowClick(row: Record<string, any>) {
+    if (!this.clickableRows) return;
+    this.dispatchEvent(
+      new CustomEvent("st-row-click", {detail: row, bubbles: true, composed: true}),
+    );
+  }
+
+  private _onRowKeydown(e: KeyboardEvent, row: Record<string, any>) {
+    if (!this.clickableRows || (e.key !== "Enter" && e.key !== " ")) return;
+    e.preventDefault();
+    this._onRowClick(row);
+  }
+
+  private _renderBody() {
+    const span = Math.max(this.columns.length, 1);
+    if (this.loading) {
+      return Array.from(
+        {length: SKELETON_ROWS},
+        () => html`
+          <tr role="row">
+            ${this.columns.map(
+              () => html`
+                <td role="cell"><st-skeleton variant="text" width="70%"></st-skeleton></td>
+              `,
+            )}
+          </tr>
+        `,
+      );
+    }
+    if (this.data.length === 0) {
+      return html`
+        <tr role="row">
+          <td role="cell" colspan=${span} class="empty-state">${this.emptyText}</td>
+        </tr>
+      `;
+    }
+    return this.data.map(
+      (row, index) => html`
+        <tr
+          role="row"
+          class=${classMap({clickable: this.clickableRows})}
+          tabindex=${ifDefined(this.clickableRows ? "0" : undefined)}
+          @click=${() => this._onRowClick(row)}
+          @keydown=${(e: KeyboardEvent) => this._onRowKeydown(e, row)}
+        >
+          ${this.columns.map(
+            (col) => html`
+              <td role="cell" class=${this._alignClass(col)} data-label=${col.header}>
+                ${col.render ? col.render(row, index) : (row[col.key] ?? "")}
+              </td>
+            `,
+          )}
+        </tr>
+      `,
+    );
+  }
+
+  private _renderHead() {
+    return html`
+      <thead role="rowgroup">
+        <tr role="row">
+          ${this.columns.map(
+            (col) => html`
+              <th
+                role="columnheader"
+                scope="col"
+                class=${this._alignClass(col)}
+                style=${ifDefined(col.width ? `width:${col.width}` : undefined)}
+              >
+                ${col.header}
+              </th>
+            `,
+          )}
+        </tr>
+      </thead>
+    `;
+  }
+
   render() {
     return html`
       <div class="table-wrapper">
-        <!-- 🚀 FIX: Explicit ARIA roles map to preserve semantics when CSS 'display' changes -->
-        <table role="table">
-          <thead role="rowgroup">
-            <tr role="row">
-              ${this.columns.map(
-                (col) => html`<th role="columnheader" scope="col">${col.header}</th>`,
-              )}
-            </tr>
-          </thead>
+        <!-- Explicit ARIA roles preserve semantics when CSS 'display' changes in vertical mode -->
+        <table role="table" aria-busy=${this.loading ? "true" : "false"}>
+          ${this.caption ? html`<caption>${this.caption}</caption>` : nothing}
+          ${this.columns.length ? this._renderHead() : nothing}
           <tbody role="rowgroup">
-            ${this.data.length === 0
-              ? html`
-                  <tr role="row">
-                    <td role="cell" colspan=${this.columns.length} class="empty-state">
-                      No data available.
-                    </td>
-                  </tr>
-                `
-              : this.data.map(
-                  (row) => html`
-                    <tr role="row">
-                      ${this.columns.map(
-                        // 🚀 FIX: Nullish coalescing prevents printing "undefined" for sparse data objects
-                        (col) => html`
-                          <td role="cell" data-label=${col.header}>${row[col.key] ?? ""}</td>
-                        `,
-                      )}
-                    </tr>
-                  `,
-                )}
+            ${this._renderBody()}
           </tbody>
         </table>
       </div>

package/src/components/team/person.ts

@@ -0,0 +1,113 @@
+import {html, css} from "lit";
+import {customElement, state} from "lit/decorators.js";
+import {resetStyles} from "../../styles/reset.js";
+import {StRowItem} from "../section/row-item.js";
+
+/**
+ * One team member inside `st-team`.
+ *
+ * Slots: `photo` (an `img`, hidden when empty), `name` (a real heading such as `<h3>`), `role`,
+ * the default slot (a short bio) and `links` (social or contact links).
+ */
+@customElement("st-person")
+export class StPerson extends StRowItem {
+  @state() private _hasPhoto = false;
+  @state() private _hasLinks = false;
+
+  static styles = [
+    resetStyles,
+    css`
+      :host {
+        display: block;
+        text-align: center;
+      }
+
+      .person {
+        display: grid;
+        justify-items: center;
+        gap: var(--st-spacing-xs);
+      }
+
+      .photo {
+        display: block;
+        overflow: hidden;
+        width: 7rem;
+        height: 7rem;
+        margin-bottom: var(--st-spacing-sm);
+        border-radius: 50%;
+        background: var(--st-color-surface-muted);
+      }
+
+      .photo[hidden] {
+        display: none;
+      }
+
+      .photo ::slotted(img) {
+        width: 100%;
+        height: 100%;
+        object-fit: cover;
+      }
+
+      ::slotted([slot="name"]) {
+        margin: 0 !important;
+        font-size: var(--st-font-size-lg) !important;
+      }
+
+      ::slotted([slot="role"]) {
+        display: block;
+        color: var(--st-color-primary-text);
+        font-size: var(--st-font-size-sm);
+        font-weight: var(--st-font-weight-bold);
+      }
+
+      .bio {
+        color: var(--st-color-text-muted);
+        font-size: var(--st-font-size-sm);
+      }
+
+      .bio ::slotted(*) {
+        margin: 0;
+      }
+
+      .links {
+        display: flex;
+        flex-wrap: wrap;
+        justify-content: center;
+        gap: var(--st-spacing-md);
+        margin-top: var(--st-spacing-sm);
+      }
+
+      .links[hidden] {
+        display: none;
+      }
+    `,
+  ];
+
+  render() {
+    return this.frame(html`
+      <div class="person">
+        <span class="photo" ?hidden=${!this._hasPhoto}>
+          <slot
+            name="photo"
+            @slotchange=${(e: Event) => (this._hasPhoto = (e.target as HTMLSlotElement).assignedNodes().length > 0)}
+          ></slot>
+        </span>
+        <slot name="name"></slot>
+        <slot name="role"></slot>
+        <div class="bio"><slot></slot></div>
+        <div class="links" ?hidden=${!this._hasLinks}>
+          <slot
+            name="links"
+            @slotchange=${(e: Event) => (this._hasLinks = (e.target as HTMLSlotElement).assignedNodes().length > 0)}
+          ></slot>
+        </div>
+      </div>
+    `);
+  }
+}
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "st-person": StPerson;
+  }
+}