@colixsystems/widget-sdk 0.284.0 → 0.285.0

package/README.md

@@ -89,7 +89,11 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.284.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+`v0.285.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+
+### What's new in 0.285.0 (contract 1.233.0)
+
+**Host only: container background patterns.** `@colixsystems/widget-sdk/host` exports `normaliseContainerPattern`, `containerPatternTile` and `containerPatternSvg`, the one definition of a layout container's `backgroundPattern` (dots, grid, lines, stripes, grain) that the web Player and the native export both tile. Nothing changes for widget authors.
 
 ### What's new in 0.284.0 (contract 1.233.0)
 

package/dist/container-pattern.cjs

@@ -0,0 +1,196 @@
+// GENERATED from container-pattern.js by scripts/generate-cjs.js — DO NOT EDIT.
+// Change container-pattern.js, then run `npm run generate:cjs` in packages/widget-sdk.
+"use strict";
+
+const { isHexColor } = require("./contract.cjs");
+
+// sc-14027 — a layout container's background pattern: dot paper, a grid, ruled
+// lines, a diagonal hatch or film grain, tiled over the fill and under the
+// scrim. The ONE definition of the vocabulary and of each tile's geometry, so
+// the web Player (a CSS background tile), the compiled Expo app (a
+// react-native-svg <Pattern>) and Mason's plan validator cannot disagree.
+//
+// Host-integration surface, re-exported from `host.js`.
+
+const CONTAINER_PATTERN_KINDS = Object.freeze([
+  "dots",
+  "grid",
+  "lines",
+  "stripes",
+  "grain",
+]);
+
+// Tile edge in px (grain: the scale of its specks). Opacity is a 0-100
+// percentage, like every other opacity a container style carries.
+const CONTAINER_PATTERN_SIZE = Object.freeze({ min: 4, max: 64, default: 12 });
+const CONTAINER_PATTERN_OPACITY = Object.freeze({ min: 0, max: 100, default: 15 });
+
+const FALLBACK_COLOR = "#000000";
+const PATTERN_KEYS = ["kind", "color", "size", "opacity"];
+
+function clampNumber(value, { min, max, default: fallback }) {
+  if (value === undefined || value === null || value === "") return fallback;
+  const n = Number(value);
+  if (!Number.isFinite(n)) return fallback;
+  return Math.min(Math.max(n, min), max);
+}
+
+function inRange(value, { min, max }) {
+  return value === undefined || (typeof value === "number" && value >= min && value <= max);
+}
+
+// Strict: what a writer (Mason) must send. The hosts clamp instead, so a
+// value only strict mode refuses still paints.
+function isStrictPattern(raw) {
+  return (
+    Object.keys(raw).every((key) => PATTERN_KEYS.includes(key)) &&
+    (raw.color === undefined || raw.color === "" || isHexColor(raw.color)) &&
+    inRange(raw.size, CONTAINER_PATTERN_SIZE) &&
+    inRange(raw.opacity, CONTAINER_PATTERN_OPACITY)
+  );
+}
+
+/**
+ * Resolve an authored `style.backgroundPattern` into what a host paints.
+ *
+ * @param {unknown} raw `{ kind, color?, size?, opacity? }`
+ * @param {string} [fallbackColor] the ink an unset colour takes, usually the surface's `onSurface`
+ * @param {{strict?: boolean}} [options] strict: refuse unknown keys and out-of-range values instead of clamping
+ * @returns {{kind: string, color: string, size: number, opacity: number}|null}
+ *   null when no recognised kind is set, so an unpatterned container paints nothing new.
+ *   `opacity` is the 0-1 alpha.
+ */
+function normaliseContainerPattern(raw, fallbackColor, { strict = false } = {}) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+  if (!CONTAINER_PATTERN_KINDS.includes(raw.kind)) return null;
+  if (strict && !isStrictPattern(raw)) return null;
+  // Hex only: the colour is written into SVG markup on the web.
+  const color = isHexColor(raw.color)
+    ? raw.color
+    : isHexColor(fallbackColor)
+      ? fallbackColor
+      : FALLBACK_COLOR;
+  const opacity = clampNumber(raw.opacity, CONTAINER_PATTERN_OPACITY) / 100;
+  if (opacity === 0) return null;
+  return {
+    kind: raw.kind,
+    color,
+    size: Math.round(clampNumber(raw.size, CONTAINER_PATTERN_SIZE)),
+    opacity,
+  };
+}
+
+const round2 = (n) => Math.round(n * 100) / 100;
+
+// The grain tile: a fixed speckle on a GRAIN_CELLS square grid, seeded so every
+// host and every render draws the same noise. Not feTurbulence: native has no
+// filter primitives, and a computed tile is identical on both hosts.
+const GRAIN_CELLS = 48;
+const GRAIN_LEVELS = [0.35, 0.6, 1];
+const GRAIN_SPECKS = (() => {
+  let seed = 0x14027;
+  const next = () => {
+    seed = (seed + 0x6d2b79f5) | 0;
+    let t = Math.imul(seed ^ (seed >>> 15), 1 | seed);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+  const byLevel = GRAIN_LEVELS.map(() => []);
+  for (let y = 0; y < GRAIN_CELLS; y += 1) {
+    for (let x = 0; x < GRAIN_CELLS; x += 1) {
+      if (next() < 0.1) byLevel[Math.floor(next() * GRAIN_LEVELS.length)].push([x, y]);
+    }
+  }
+  return byLevel;
+})();
+
+function grainTile(size) {
+  const cell = size / CONTAINER_PATTERN_SIZE.default;
+  const c = round2(cell);
+  return {
+    size: round2(GRAIN_CELLS * cell),
+    paths: GRAIN_SPECKS.map((specks, i) => ({
+      d: specks.map(([x, y]) => `M${round2(x * cell)} ${round2(y * cell)}h${c}v${c}h-${c}z`).join(""),
+      fill: true,
+      alpha: GRAIN_LEVELS[i],
+    })),
+  };
+}
+
+// Tiles depend only on kind and the clamped size, so the cache stays small.
+const TILE_CACHE = new Map();
+
+/**
+ * The repeating tile for a resolved pattern, as plain SVG path data both hosts
+ * draw: the web as an SVG string, native as react-native-svg `<Path>`s.
+ *
+ * @param {{kind: string, size: number}} pattern output of {@link normaliseContainerPattern}
+ * @returns {{size: number, paths: Array<{d: string, fill?: boolean, strokeWidth?: number, alpha?: number}>}}
+ *   shared and cached: do not mutate it.
+ */
+function containerPatternTile(pattern) {
+  const key = `${pattern.kind}:${pattern.size}`;
+  if (!TILE_CACHE.has(key)) TILE_CACHE.set(key, buildTile(pattern.kind, pattern.size));
+  return TILE_CACHE.get(key);
+}
+
+function buildTile(kind, s) {
+  if (kind === "grain") return grainTile(s);
+  if (kind === "dots") {
+    const r = round2(Math.max(1, s / 8));
+    const c = s / 2;
+    return {
+      size: s,
+      paths: [{ d: `M${round2(c - r)} ${c}a${r} ${r} 0 1 0 ${round2(r * 2)} 0a${r} ${r} 0 1 0 -${round2(r * 2)} 0z`, fill: true }],
+    };
+  }
+  if (kind === "grid") {
+    return { size: s, paths: [{ d: `M0 0.5H${s}M0.5 0V${s}`, strokeWidth: 1 }] };
+  }
+  if (kind === "lines") {
+    return { size: s, paths: [{ d: `M0 0.5H${s}`, strokeWidth: 1 }] };
+  }
+  // stripes: a 45° hatch. The two corner segments complete the stripe the
+  // neighbouring tiles cut, so the hatch runs unbroken across tile edges.
+  const h = s / 2;
+  return {
+    size: s,
+    paths: [
+      {
+        d: `M0 ${s}L${s} 0M-${h} ${h}L${h} -${h}M${h} ${s + h}L${s + h} ${h}`,
+        strokeWidth: round2(Math.max(1, s / 4)),
+      },
+    ],
+  };
+}
+
+/**
+ * The tile as standalone SVG markup, for the web host's repeating CSS
+ * background. The colour is hex-validated by {@link normaliseContainerPattern}
+ * and the path data is numeric, so nothing authored reaches the markup raw.
+ *
+ * @param {{kind: string, color: string, size: number}} pattern
+ * @returns {string}
+ */
+function containerPatternSvg(pattern) {
+  const tile = containerPatternTile(pattern);
+  const paths = tile.paths
+    .map((p) => {
+      const paint = p.fill
+        ? `fill="${pattern.color}"`
+        : `fill="none" stroke="${pattern.color}" stroke-width="${p.strokeWidth}"`;
+      const alpha = p.alpha === undefined ? "" : ` opacity="${p.alpha}"`;
+      return `<path d="${p.d}" ${paint}${alpha}/>`;
+    })
+    .join("");
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${tile.size}" height="${tile.size}">${paths}</svg>`;
+}
+
+module.exports = {
+  CONTAINER_PATTERN_KINDS,
+  CONTAINER_PATTERN_SIZE,
+  CONTAINER_PATTERN_OPACITY,
+  normaliseContainerPattern,
+  containerPatternTile,
+  containerPatternSvg,
+};

package/dist/container-pattern.js

@@ -0,0 +1,191 @@
+// sc-14027 — a layout container's background pattern: dot paper, a grid, ruled
+// lines, a diagonal hatch or film grain, tiled over the fill and under the
+// scrim. The ONE definition of the vocabulary and of each tile's geometry, so
+// the web Player (a CSS background tile), the compiled Expo app (a
+// react-native-svg <Pattern>) and Mason's plan validator cannot disagree.
+//
+// Host-integration surface, re-exported from `host.js`.
+import { isHexColor } from "./contract.js";
+
+const CONTAINER_PATTERN_KINDS = Object.freeze([
+  "dots",
+  "grid",
+  "lines",
+  "stripes",
+  "grain",
+]);
+
+// Tile edge in px (grain: the scale of its specks). Opacity is a 0-100
+// percentage, like every other opacity a container style carries.
+const CONTAINER_PATTERN_SIZE = Object.freeze({ min: 4, max: 64, default: 12 });
+const CONTAINER_PATTERN_OPACITY = Object.freeze({ min: 0, max: 100, default: 15 });
+
+const FALLBACK_COLOR = "#000000";
+const PATTERN_KEYS = ["kind", "color", "size", "opacity"];
+
+function clampNumber(value, { min, max, default: fallback }) {
+  if (value === undefined || value === null || value === "") return fallback;
+  const n = Number(value);
+  if (!Number.isFinite(n)) return fallback;
+  return Math.min(Math.max(n, min), max);
+}
+
+function inRange(value, { min, max }) {
+  return value === undefined || (typeof value === "number" && value >= min && value <= max);
+}
+
+// Strict: what a writer (Mason) must send. The hosts clamp instead, so a
+// value only strict mode refuses still paints.
+function isStrictPattern(raw) {
+  return (
+    Object.keys(raw).every((key) => PATTERN_KEYS.includes(key)) &&
+    (raw.color === undefined || raw.color === "" || isHexColor(raw.color)) &&
+    inRange(raw.size, CONTAINER_PATTERN_SIZE) &&
+    inRange(raw.opacity, CONTAINER_PATTERN_OPACITY)
+  );
+}
+
+/**
+ * Resolve an authored `style.backgroundPattern` into what a host paints.
+ *
+ * @param {unknown} raw `{ kind, color?, size?, opacity? }`
+ * @param {string} [fallbackColor] the ink an unset colour takes, usually the surface's `onSurface`
+ * @param {{strict?: boolean}} [options] strict: refuse unknown keys and out-of-range values instead of clamping
+ * @returns {{kind: string, color: string, size: number, opacity: number}|null}
+ *   null when no recognised kind is set, so an unpatterned container paints nothing new.
+ *   `opacity` is the 0-1 alpha.
+ */
+function normaliseContainerPattern(raw, fallbackColor, { strict = false } = {}) {
+  if (!raw || typeof raw !== "object" || Array.isArray(raw)) return null;
+  if (!CONTAINER_PATTERN_KINDS.includes(raw.kind)) return null;
+  if (strict && !isStrictPattern(raw)) return null;
+  // Hex only: the colour is written into SVG markup on the web.
+  const color = isHexColor(raw.color)
+    ? raw.color
+    : isHexColor(fallbackColor)
+      ? fallbackColor
+      : FALLBACK_COLOR;
+  const opacity = clampNumber(raw.opacity, CONTAINER_PATTERN_OPACITY) / 100;
+  if (opacity === 0) return null;
+  return {
+    kind: raw.kind,
+    color,
+    size: Math.round(clampNumber(raw.size, CONTAINER_PATTERN_SIZE)),
+    opacity,
+  };
+}
+
+const round2 = (n) => Math.round(n * 100) / 100;
+
+// The grain tile: a fixed speckle on a GRAIN_CELLS square grid, seeded so every
+// host and every render draws the same noise. Not feTurbulence: native has no
+// filter primitives, and a computed tile is identical on both hosts.
+const GRAIN_CELLS = 48;
+const GRAIN_LEVELS = [0.35, 0.6, 1];
+const GRAIN_SPECKS = (() => {
+  let seed = 0x14027;
+  const next = () => {
+    seed = (seed + 0x6d2b79f5) | 0;
+    let t = Math.imul(seed ^ (seed >>> 15), 1 | seed);
+    t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t;
+    return ((t ^ (t >>> 14)) >>> 0) / 4294967296;
+  };
+  const byLevel = GRAIN_LEVELS.map(() => []);
+  for (let y = 0; y < GRAIN_CELLS; y += 1) {
+    for (let x = 0; x < GRAIN_CELLS; x += 1) {
+      if (next() < 0.1) byLevel[Math.floor(next() * GRAIN_LEVELS.length)].push([x, y]);
+    }
+  }
+  return byLevel;
+})();
+
+function grainTile(size) {
+  const cell = size / CONTAINER_PATTERN_SIZE.default;
+  const c = round2(cell);
+  return {
+    size: round2(GRAIN_CELLS * cell),
+    paths: GRAIN_SPECKS.map((specks, i) => ({
+      d: specks.map(([x, y]) => `M${round2(x * cell)} ${round2(y * cell)}h${c}v${c}h-${c}z`).join(""),
+      fill: true,
+      alpha: GRAIN_LEVELS[i],
+    })),
+  };
+}
+
+// Tiles depend only on kind and the clamped size, so the cache stays small.
+const TILE_CACHE = new Map();
+
+/**
+ * The repeating tile for a resolved pattern, as plain SVG path data both hosts
+ * draw: the web as an SVG string, native as react-native-svg `<Path>`s.
+ *
+ * @param {{kind: string, size: number}} pattern output of {@link normaliseContainerPattern}
+ * @returns {{size: number, paths: Array<{d: string, fill?: boolean, strokeWidth?: number, alpha?: number}>}}
+ *   shared and cached: do not mutate it.
+ */
+function containerPatternTile(pattern) {
+  const key = `${pattern.kind}:${pattern.size}`;
+  if (!TILE_CACHE.has(key)) TILE_CACHE.set(key, buildTile(pattern.kind, pattern.size));
+  return TILE_CACHE.get(key);
+}
+
+function buildTile(kind, s) {
+  if (kind === "grain") return grainTile(s);
+  if (kind === "dots") {
+    const r = round2(Math.max(1, s / 8));
+    const c = s / 2;
+    return {
+      size: s,
+      paths: [{ d: `M${round2(c - r)} ${c}a${r} ${r} 0 1 0 ${round2(r * 2)} 0a${r} ${r} 0 1 0 -${round2(r * 2)} 0z`, fill: true }],
+    };
+  }
+  if (kind === "grid") {
+    return { size: s, paths: [{ d: `M0 0.5H${s}M0.5 0V${s}`, strokeWidth: 1 }] };
+  }
+  if (kind === "lines") {
+    return { size: s, paths: [{ d: `M0 0.5H${s}`, strokeWidth: 1 }] };
+  }
+  // stripes: a 45° hatch. The two corner segments complete the stripe the
+  // neighbouring tiles cut, so the hatch runs unbroken across tile edges.
+  const h = s / 2;
+  return {
+    size: s,
+    paths: [
+      {
+        d: `M0 ${s}L${s} 0M-${h} ${h}L${h} -${h}M${h} ${s + h}L${s + h} ${h}`,
+        strokeWidth: round2(Math.max(1, s / 4)),
+      },
+    ],
+  };
+}
+
+/**
+ * The tile as standalone SVG markup, for the web host's repeating CSS
+ * background. The colour is hex-validated by {@link normaliseContainerPattern}
+ * and the path data is numeric, so nothing authored reaches the markup raw.
+ *
+ * @param {{kind: string, color: string, size: number}} pattern
+ * @returns {string}
+ */
+function containerPatternSvg(pattern) {
+  const tile = containerPatternTile(pattern);
+  const paths = tile.paths
+    .map((p) => {
+      const paint = p.fill
+        ? `fill="${pattern.color}"`
+        : `fill="none" stroke="${pattern.color}" stroke-width="${p.strokeWidth}"`;
+      const alpha = p.alpha === undefined ? "" : ` opacity="${p.alpha}"`;
+      return `<path d="${p.d}" ${paint}${alpha}/>`;
+    })
+    .join("");
+  return `<svg xmlns="http://www.w3.org/2000/svg" width="${tile.size}" height="${tile.size}">${paths}</svg>`;
+}
+
+export {
+  CONTAINER_PATTERN_KINDS,
+  CONTAINER_PATTERN_SIZE,
+  CONTAINER_PATTERN_OPACITY,
+  normaliseContainerPattern,
+  containerPatternTile,
+  containerPatternSvg,
+};

package/dist/host.d.ts

@@ -712,3 +712,33 @@ export const DARK_PALETTE_KEYS: readonly string[];
  * appearance setting stores it: the base light, `dark` the dark palette.
  */
 export function themeInBothModes<T>(theme: T, mode: AppearanceMode, twin: unknown): T;
+
+/** A container background pattern, resolved for painting. `opacity` is 0-1. */
+export interface ContainerPattern {
+  kind: "dots" | "grid" | "lines" | "stripes" | "grain";
+  color: string;
+  size: number;
+  opacity: number;
+}
+
+/** One path of a pattern tile: filled, or stroked at `strokeWidth`. */
+export interface ContainerPatternPath {
+  d: string;
+  fill?: boolean;
+  strokeWidth?: number;
+  alpha?: number;
+}
+
+export const CONTAINER_PATTERN_KINDS: readonly ContainerPattern["kind"][];
+export const CONTAINER_PATTERN_SIZE: { readonly min: number; readonly max: number; readonly default: number };
+export const CONTAINER_PATTERN_OPACITY: { readonly min: number; readonly max: number; readonly default: number };
+/** A container's `style.backgroundPattern`, or null when it names no known kind. */
+export function normaliseContainerPattern(
+  raw: unknown,
+  fallbackColor?: string,
+  options?: { strict?: boolean },
+): ContainerPattern | null;
+/** The repeating tile both hosts draw. */
+export function containerPatternTile(pattern: ContainerPattern): { size: number; paths: ContainerPatternPath[] };
+/** The tile as standalone SVG markup, for a CSS background. */
+export function containerPatternSvg(pattern: ContainerPattern): string;

package/dist/host.js

@@ -173,3 +173,14 @@ export {
   dateTimeLocalInputToIso,
   formatDisplayLabel as formatDateTimeLabel,
 } from "./datetimepicker-format.js";
+
+// sc-14027: a container's background pattern — vocabulary and tile geometry,
+// so the Player's CSS tile and the export's <Pattern> draw the same thing.
+export {
+  CONTAINER_PATTERN_KINDS,
+  CONTAINER_PATTERN_SIZE,
+  CONTAINER_PATTERN_OPACITY,
+  normaliseContainerPattern,
+  containerPatternTile,
+  containerPatternSvg,
+} from "./container-pattern.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.284.0",
+  "version": "0.285.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "homepage": "https://github.com/Colix-AB/AppStudio",
   "type": "module",