@colixsystems/widget-sdk 0.245.0 → 0.247.0

package/dist/grid-logic.js

@@ -0,0 +1,222 @@
+// The `<Grid>` arithmetic, without a renderer: how many cells fit a line, how
+// the cells split into balanced lines, and how big a definite-size cell is.
+// These are the formulas the AI widget builder is taught for a grid it lays
+// out by hand, so the component and that guidance cannot disagree.
+
+import { widthTier } from "./container-width.js";
+
+export const GRID_BALANCES = Object.freeze(["cards", "tiles"]);
+export const DEFAULT_GRID_BALANCE = "cards";
+/** The card width a cards grid counts with when it is given none. */
+export const DEFAULT_MIN_CELL_WIDTH = 240;
+/** The smallest a definite-size cell gets when `cell.min` is not given. */
+export const DEFAULT_CELL_MIN = 32;
+export const DEFAULT_GRID_GAP = "md";
+/** A tile row's per-line ceiling at each width tier. */
+export const TILE_COLUMNS_BY_TIER = Object.freeze({ narrow: 2, medium: 3, wide: 4 });
+
+function positiveInt(value) {
+  const n = Math.floor(Number(value));
+  return Number.isFinite(n) && n >= 1 ? n : null;
+}
+
+function nonNegative(value) {
+  const n = Number(value);
+  return Number.isFinite(n) && n >= 0 ? n : null;
+}
+
+/** A requested balance, or cards when it names none we draw. */
+export function gridBalance(balance) {
+  return GRID_BALANCES.includes(balance) ? balance : DEFAULT_GRID_BALANCE;
+}
+
+/**
+ * The gap in pixels: a theme spacing name (`"xs"` … `"xl"`) or a number.
+ *
+ * @param {string|number|undefined} gap
+ * @param {Record<string, number>} spacing the theme's spacing scale
+ */
+export function resolveGridGap(gap, spacing) {
+  const scale = spacing || {};
+  const asNumber = nonNegative(gap);
+  if (typeof gap === "number" && asNumber !== null) return asNumber;
+  const named = typeof gap === "string" ? nonNegative(scale[gap]) : null;
+  if (named !== null) return named;
+  return nonNegative(scale[DEFAULT_GRID_GAP]) ?? 16;
+}
+
+/** How many cells of at least `minCellWidth` fit `width`: at least one. */
+export function cellsPerLine(width, gap, minCellWidth) {
+  return Math.max(1, Math.floor((width + gap) / (minCellWidth + gap)));
+}
+
+/**
+ * Tiles stretch, so the remainder spreads over every line: 5 at 4 are 3 + 2,
+ * 7 at 3 are 3 + 2 + 2, and a short line only ever comes last.
+ */
+export function tileLineLengths(count, max) {
+  if (!(count > 0)) return [];
+  const lines = Math.ceil(count / max);
+  const base = Math.floor(count / lines);
+  const extra = count % lines;
+  return Array.from({ length: lines }, (_, i) => base + (i < extra ? 1 : 0));
+}
+
+/**
+ * Cards keep one width, so every line but the last is full: 6 that fit 5 are
+ * 3 + 3, 10 that fit 4 are 4 + 4 + 2. `cols` is the width every line keeps.
+ */
+export function cardLineLengths(count, max) {
+  if (!(count > 0)) return { cols: 0, lengths: [] };
+  const lines = Math.ceil(count / max);
+  const cols = Math.ceil(count / lines);
+  const lengths = Array.from({ length: lines }, (_, i) => Math.min(cols, count - i * cols));
+  return { cols, lengths };
+}
+
+/** A definite cell: the share of the line each column gets, clamped. */
+export function clampCellSize(usable, gap, columns, min, max) {
+  const share = Math.floor((usable - gap * (columns - 1)) / columns);
+  return Math.max(min, Math.min(share, max));
+}
+
+function exactLines(count, columns) {
+  const lines = Math.ceil(count / columns);
+  return Array.from({ length: lines }, (_, i) => Math.min(columns, count - i * columns));
+}
+
+function definiteCell(cell) {
+  if (!cell || typeof cell !== "object") return null;
+  const max = nonNegative(cell.max);
+  if (max === null || max <= 0) return null;
+  const min = Math.min(nonNegative(cell.min) ?? DEFAULT_CELL_MIN, max);
+  return { min, max };
+}
+
+/**
+ * Lay out `count` cells in a `width`-wide box.
+ *
+ * Returns `null` while a count or a size depends on a width not yet measured
+ * (0), so the grid renders nothing size-dependent until it arrives. Otherwise
+ * `lengths` is the number of cells on each line, `slots` the positions every
+ * line is padded up to (null when lines stretch, as tiles do), and, for
+ * definite cells, `cellSize`, the block's `blockWidth` and its `align`: the
+ * block centres, but one wider than the grid starts at the leading edge so
+ * only its far end is cut off.
+ *
+ * @param {{count: number, width: number, gap: number, balance?: string,
+ *   minCellWidth?: number, maxColumns?: number, columns?: number,
+ *   cell?: {min?: number, max: number}}} input
+ */
+export function planGrid(input) {
+  const count = Math.max(0, Math.floor(Number(input.count) || 0));
+  const width = Number(input.width) > 0 ? Number(input.width) : 0;
+  const gap = nonNegative(input.gap) ?? 0;
+  const balance = gridBalance(input.balance);
+  const columns = positiveInt(input.columns);
+  const maxColumns = positiveInt(input.maxColumns);
+  const minCellWidth = nonNegative(input.minCellWidth);
+  const cell = definiteCell(input.cell);
+  const capped = (n) => (maxColumns ? Math.min(n, maxColumns) : n);
+
+  if (cell) {
+    if (width === 0) return null;
+    let perLine = columns;
+    if (!perLine) {
+      // As many columns as keep each cell at or under its max, filling the line.
+      perLine = capped(Math.max(1, Math.ceil((width + gap) / (cell.max + gap))));
+      while (perLine > 1 && clampCellSize(width, gap, perLine, 0, cell.max) < cell.min) perLine -= 1;
+    }
+    const plan = columns
+      ? { cols: columns, lengths: exactLines(count, columns) }
+      : cardLineLengths(count, perLine);
+    const cols = plan.cols || perLine;
+    const cellSize = clampCellSize(width, gap, cols, cell.min, cell.max);
+    const blockWidth = cellSize * cols + gap * (cols - 1);
+    return {
+      lengths: plan.lengths,
+      slots: cols,
+      cellSize,
+      blockWidth,
+      align: blockWidth > width ? "flex-start" : "center",
+    };
+  }
+
+  if (columns) {
+    return { lengths: exactLines(count, columns), slots: columns, cellSize: null, blockWidth: null };
+  }
+
+  const counted = minCellWidth !== null && minCellWidth > 0 ? minCellWidth : null;
+  if (balance === "tiles") {
+    let max;
+    if (counted) {
+      if (width === 0) return null;
+      max = capped(cellsPerLine(width, gap, counted));
+    } else if (maxColumns) {
+      max = maxColumns;
+    } else {
+      if (width === 0) return null;
+      max = TILE_COLUMNS_BY_TIER[widthTier(width)];
+    }
+    return { lengths: tileLineLengths(count, max), slots: null, cellSize: null, blockWidth: null };
+  }
+
+  if (width === 0) return null;
+  const max = capped(cellsPerLine(width, gap, counted || DEFAULT_MIN_CELL_WIDTH));
+  const { cols, lengths } = cardLineLengths(count, max);
+  return { lengths, slots: cols, cellSize: null, blockWidth: null };
+}
+
+/** Split `items` into lines of the planned lengths. */
+export function splitIntoLines(items, lengths) {
+  const lines = [];
+  let start = 0;
+  for (const length of lengths) {
+    lines.push(items.slice(start, start + length));
+    start += length;
+  }
+  return lines;
+}
+
+// Floored so a line of percentages never sums past 100% and wraps early.
+function percentOf(parts) {
+  return `${Math.floor((100 / parts) * 10000) / 10000}%`;
+}
+
+function place(plan, gap, position, perLine) {
+  if (plan.cellSize !== null) return { width: plan.cellSize, padStart: 0, padEnd: 0 };
+  // The gap is split between neighbours, so every cell keeps an equal share.
+  return {
+    width: percentOf(perLine),
+    padStart: (gap * position) / perLine,
+    padEnd: (gap * (perLine - 1 - position)) / perLine,
+  };
+}
+
+/**
+ * Where each cell sits in the ONE wrapping box the grid draws: its `line`,
+ * its `width` (pixels for a definite cell, else a share of the box) and the
+ * `padStart` / `padEnd` that make up the gap between flexible neighbours.
+ * `spacers` are the empty cells that pad the last line to `slots`. Every
+ * cell stays a child of the same box, so moving it to another line never
+ * remounts it.
+ *
+ * @param {{lengths: number[], slots: number|null, cellSize: number|null}} plan
+ * @param {number} gap
+ */
+export function placeCells(plan, gap) {
+  const cells = [];
+  let spacers = [];
+  plan.lengths.forEach((length, line) => {
+    const perLine = plan.slots ?? length;
+    for (let position = 0; position < length; position += 1) {
+      cells.push({ line, ...place(plan, gap, position, perLine) });
+    }
+    if (line === plan.lengths.length - 1 && plan.slots !== null) {
+      spacers = Array.from({ length: Math.max(0, plan.slots - length) }, (_, s) =>
+        place(plan, gap, length + s, perLine),
+      );
+    }
+  });
+  return { cells, spacers };
+}

package/dist/grid-view.js

@@ -0,0 +1,109 @@
+// The ONE implementation behind the `<Grid>` SDK primitive. The platform
+// bindings (`grid.js` / `grid.native.js`) differ only in where `View` comes
+// from, so the hosts lay a grid out the same way.
+//
+// The grid measures an inner View that carries no padding, so a `style`
+// padding on the grid is never counted into the width its cells share.
+
+import React from "react";
+import { useContainerWidth, useHostTheme } from "./hooks.js";
+import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
+import { placeCells, planGrid, resolveGridGap } from "./grid-logic.js";
+
+const h = React.createElement;
+
+const HIDDEN_FROM_READERS = {
+  "aria-hidden": true,
+  accessibilityElementsHidden: true,
+  importantForAccessibility: "no-hide-descendants",
+};
+
+function cellStyle(place, plan, square, hidden) {
+  const own = hidden ? { pointerEvents: "none" } : null;
+  if (plan.cellSize !== null) {
+    const size = { width: plan.cellSize, flexShrink: 0, ...own };
+    return square ? { ...size, height: plan.cellSize } : size;
+  }
+  return { width: place.width, paddingStart: place.padStart, paddingEnd: place.padEnd, ...own };
+}
+
+/**
+ * Bind the shared grid to one platform's primitives.
+ *
+ * @param {{View: any}} rn
+ */
+export function makeGrid(rn) {
+  const { View } = rn;
+
+  // A flexible square cell squares its content box, inside the gap padding.
+  function cell(key, style, square, flexible, child, extra) {
+    const inner = square && flexible ? h(View, { style: { aspectRatio: 1 } }, child) : child;
+    return h(View, { key, style, ...extra }, inner);
+  }
+
+  function Grid({
+    children,
+    balance,
+    minCellWidth,
+    maxColumns,
+    columns,
+    cell: cellSize,
+    square = false,
+    gap,
+    style,
+    testID,
+    accessibilityLabel,
+  }) {
+    const theme = useHostTheme() || DEFAULT_THEME_TOKENS;
+    const spacing = theme.spacing || DEFAULT_THEME_TOKENS.spacing;
+    const space = resolveGridGap(gap, spacing);
+    const [width, onLayout] = useContainerWidth();
+    const items = React.Children.toArray(children);
+    const plan = planGrid({
+      count: items.length,
+      width,
+      gap: space,
+      balance,
+      minCellWidth,
+      maxColumns,
+      columns,
+      cell: cellSize,
+    });
+
+    let content = null;
+    if (plan) {
+      const isSquare = square === true;
+      const flexible = plan.cellSize === null;
+      const { cells, spacers } = placeCells(plan, space);
+      const wrap = flexible
+        ? { flexDirection: "row", flexWrap: "wrap", rowGap: space }
+        : {
+            flexDirection: "row",
+            flexWrap: "wrap",
+            gap: space,
+            width: plan.blockWidth,
+            alignSelf: plan.align,
+          };
+      // One box for every cell, so a cell changing line keeps its state.
+      content = h(
+        View,
+        { style: wrap },
+        ...items.map((child, i) =>
+          cell(child.key, cellStyle(cells[i], plan, isSquare, false), isSquare, flexible, child),
+        ),
+        ...spacers.map((place, s) =>
+          cell(`spacer-${s}`, cellStyle(place, plan, isSquare, true), isSquare, flexible, null, HIDDEN_FROM_READERS),
+        ),
+      );
+    }
+
+    const named = accessibilityLabel ? { role: "group", accessibilityLabel } : null;
+    return h(
+      View,
+      { testID, ...named, style: [{ alignSelf: "stretch" }, style] },
+      h(View, { onLayout }, content),
+    );
+  }
+
+  return Grid;
+}

package/dist/grid.js

@@ -0,0 +1,7 @@
+// `<Grid>` (web). Binds ./grid-view.js to react-native-web; see
+// ./primitives.js for why not the bare specifier.
+
+import * as ReactNative from "react-native-web";
+import { makeGrid } from "./grid-view.js";
+
+export const Grid = makeGrid({ View: ReactNative.View });

package/dist/grid.native.js

@@ -0,0 +1,7 @@
+// `<Grid>` (native). Binds ./grid-view.js to React Native's own primitives;
+// only the import differs from ./grid.js.
+
+import { View } from "react-native";
+import { makeGrid } from "./grid-view.js";
+
+export const Grid = makeGrid({ View });

package/dist/host.d.ts

@@ -51,6 +51,12 @@ export function bannerScopeDefaults(theme: unknown): Record<string, string | num
  */
 export function chipScopeDefaults(theme: unknown): Record<string, string | number>;
 
+/**
+ * What each token of the `chart` component scope resolves to while unset,
+ * keyed by token name: the theme colours `<Chart>` paints an unthemed app with.
+ */
+export function chartScopeDefaults(theme: unknown): Record<string, string | number>;
+
 /**
  * What each token of the `search` component scope resolves to while unset,
  * keyed by token name: the input look `<SearchField>` falls back to.

package/dist/host.js

@@ -54,6 +54,8 @@ export { resolveModalTokens, modalScopeDefaults } from "./modal-tokens.js";
 // What each `chip` scope token resolves to while unset, for the Studio's
 // Design page to preview beside its controls.
 export { chipScopeDefaults } from "./chip-tokens.js";
+// The theme colours each unset `chart` token falls back to, for the same page.
+export { chartScopeDefaults } from "./chart-tokens.js";
 // The input look each unset `search` token falls back to, for the same page.
 export { searchScopeDefaults } from "./search-field-tokens.js";